{"record":{"id":"6886e361a5412906","repo":"medusajs/medusa","slug":"context-workflowid-when-name-should-be-defin","errorCode":null,"errorMessage":"${context.workflowId}: \"when\" name should be defined. A random one will be assigned to it, which is not recommended for production.\n","messagePattern":"(.+?): \"when\" name should be defined\\. A random one will be assigned to it, which is not recommended for production\\.\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/core/workflows-sdk/src/utils/composer/when.ts","lineNumber":128,"sourceCode":"  return {\n    then: (fn) => {\n      thenCalled = true\n      const ret = fn()\n      let returnStep = ret\n\n      const applyCondition =\n        global[OrchestrationUtils.SymbolMedusaWorkflowComposerCondition].steps\n\n      if (\n        isDefined(ret) &&\n        ret?.__type !== OrchestrationUtils.SymbolWorkflowStep\n      ) {\n        if (!isDefined(name)) {\n          name = \"when-then-\" + ulid()\n          const context =\n            global[OrchestrationUtils.SymbolMedusaWorkflowComposerContext]\n\n          console.warn(\n            `${context.workflowId}: \"when\" name should be defined. A random one will be assigned to it, which is not recommended for production.\\n`,\n            condition.toString()\n          )\n        }\n\n        const retStep = createStep(\n          name,\n          ({ input }: { input: any }) => new StepResponse(input)\n        )\n\n        /**\n         * object ret = { result, hooks }\n         */\n        if (isObject(ret) && \"hooks\" in ret && \"result\" in ret) {\n          returnStep = {\n            hooks: ret.hooks,\n            result: retStep({ input: ret.result }),\n          }","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/core/workflows-sdk/src/utils/composer/when.ts#L110-L146","documentation":"Inside createWorkflow, the when()/when.condition conditional helper needs a stable `name` so the generated step has a deterministic ID across runs and servers. If you omit the name, a random 'when-then-<ulid>' is generated per composition, which makes workflow step IDs non-deterministic and can break caching/reproducibility/inspection in production.","triggerScenarios":"Calling when(...) without a subsequent .named('...')/name argument inside workflows like refreshCartItemsWorkflow or any custom workflow — i.e. when(input, ({ x }) => x !== undefined).then(...) with no name provided.","commonSituations":"Writing new workflow composition following old examples that don't name when-blocks; upgrading Medusa versions where naming was introduced as recommended practice; distributing workflows across multiple instances where random IDs cause inconsistent step identities.","solutions":["Give every when-block a stable name using .named(\"refreshWhen\") (or the naming API on the when clause) inside createWorkflow","Audit workflows for anonymous when() calls: the warning prints the condition source, use it to locate the call site"],"exampleFix":"// before\nwhen(cart, ({ id }) => !!id).then(() => updateItemsStep(input.items))\n\n// after\nwhen(cart, ({ id }) => !!id, \"cart-exists\").then(() =>\n  updateItemsStep(input.items)\n)","handlingStrategy":"validation","validationCode":"// always name when-blocks\nwhen(input, condFn, \"my-stable-when-name\").then(() => step())","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass/make a stable name for when() in production workflows","Search the codebase for `when(` without a name before releases","Treat this warning as a code-review blocker"],"tags":["workflows-sdk","when-condition","determinism","step-id"],"backgroundTag":"unnamed-workflow-branch","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}