Skip to content

bug: a raw 64-character idempotencyKey skips run scope #5130

Open

Description

@heykadirhan

Provide environment information

System: macOS 27.2, arm64
Node: 26.13.0
npm: 11.20.0
@trigger.dev/core: 4.8.5 (same code on main at 2fbd5c7)

Describe the bug

The docs say a raw string passed as idempotencyKey defaults to run scope. A string of exactly 64 characters doesn't get it.

makeIdempotencyKey calls isIdempotencyKey, which returns true for any 64-character string (idempotencyKeys.ts#L53-L62, #L91-L105). So the key goes to the API unchanged, without the parent run ID. The catalog doesn't know the string either, so trigger_internal sends no idempotencyKeyOptions (shared.ts#L2442-L2445). The key ends up global.

A SHA-256 hex digest is 64 characters, and hashing your own dedup identity is a common way to build a key (#4626 says the same). So idempotencyKey: sha256(orderId) inside a task dedupes across parent runs. If a replay of the parent, or the next run of a scheduled parent, triggers the child with the same digest within the 30-day default TTL, it gets the existing child run back instead of a new one. With a key of any other length it would get a new run.

Expected: a raw string gets run scope whatever its length, as the docs say. #4626 removed this assumption from reset(). The trigger path still has it.

Reproduction repo

No repo needed, the script is below. Source:

export function isIdempotencyKey(
value: string | string[] | IdempotencyKey
): value is IdempotencyKey {
// Cannot check the brand at runtime because it doesn't exist (it's a TypeScript-only construct)
// Check for primitive strings only (we no longer use String objects)
if (typeof value === "string") {
return value.length === 64;
}
return false;
}

To reproduce

The script uses the published @trigger.dev/core and makes no API calls. It sets a task context for two different parent runs and prints the key the SDK would send in each.

import { createHash } from "node:crypto";
import { makeIdempotencyKey, taskContext } from "@trigger.dev/core/v3";

const insideParentRun = (runId) =>
  taskContext.setGlobalTaskContext({
    ctx: { run: { id: runId }, attempt: { number: 1 } },
    worker: {},
  });

const shortKey = "order-1234";
const digestKey = createHash("sha256").update("order-1234").digest("hex");

const keysFor = async (runId) => {
  insideParentRun(runId);
  return {
    short: await makeIdempotencyKey(shortKey),
    digest: await makeIdempotencyKey(digestKey),
  };
};

const runA = await keysFor("run_parent_a");
const runB = await keysFor("run_parent_b");

console.log(`digest key length: ${digestKey.length}`);
console.log(`10-char key, run-scoped (differs per parent run): ${runA.short !== runB.short}`);
console.log(`64-char key, run-scoped (differs per parent run): ${runA.digest !== runB.digest}`);
console.log(`64-char key sent as-is: ${runA.digest === digestKey}`);
npm i @trigger.dev/core@4.8.5 && node repro.mjs

Output:

digest key length: 64
10-char key, run-scoped (differs per parent run): true
64-char key, run-scoped (differs per parent run): false
64-char key sent as-is: true

Suggested fix

Do what #4626 did for reset(): treat a 64-character string as already hashed only when the catalog knows it (getIdempotencyKeyOptions(key) !== undefined). Otherwise hash it with run scope, like any other raw string.

One case gets worse with that change: a key made with idempotencyKeys.create() in another process, or in an earlier run, since the catalog is cleared at each run boundary. For example, a key created in a backend and passed to a task in the payload. The catalog doesn't know it, so it would be hashed a second time. If that case matters, the SDK needs a marker it can check at trigger time, such as a prefix on keys from create(). Until then, one line in the idempotency docs saying that 64-character raw strings are sent as-is would help.

Additional information

I found this by reading the source after seeing #4626, and checked it with the script above. I haven't tested it against a deployed project.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions