medusajs/medusa · warning

${context.workflowId}: "when" name should be defined. A rand

Error message

${context.workflowId}: "when" name should be defined. A random one will be assigned to it, which is not recommended for production.

What it means

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.

Source

Thrown at packages/core/workflows-sdk/src/utils/composer/when.ts:128

  return {
    then: (fn) => {
      thenCalled = true
      const ret = fn()
      let returnStep = ret

      const applyCondition =
        global[OrchestrationUtils.SymbolMedusaWorkflowComposerCondition].steps

      if (
        isDefined(ret) &&
        ret?.__type !== OrchestrationUtils.SymbolWorkflowStep
      ) {
        if (!isDefined(name)) {
          name = "when-then-" + ulid()
          const context =
            global[OrchestrationUtils.SymbolMedusaWorkflowComposerContext]

          console.warn(
            `${context.workflowId}: "when" name should be defined. A random one will be assigned to it, which is not recommended for production.\n`,
            condition.toString()
          )
        }

        const retStep = createStep(
          name,
          ({ input }: { input: any }) => new StepResponse(input)
        )

        /**
         * object ret = { result, hooks }
         */
        if (isObject(ret) && "hooks" in ret && "result" in ret) {
          returnStep = {
            hooks: ret.hooks,
            result: retStep({ input: ret.result }),
          }

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Give every when-block a stable name using .named("refreshWhen") (or the naming API on the when clause) inside createWorkflow
2. Audit workflows for anonymous when() calls: the warning prints the condition source, use it to locate the call site

Example fix

// before
when(cart, ({ id }) => !!id).then(() => updateItemsStep(input.items))

// after
when(cart, ({ id }) => !!id, "cart-exists").then(() =>
  updateItemsStep(input.items)
)

// always name when-blocks
when(input, condFn, "my-stable-when-name").then(() => step())

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Config is not available for the input object.

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/6886e361a5412906. Report an issue: GitHub.