medusajs/medusa · error · Error

Workflow registration requires id. Received: ${JSON.stringif

Error message

Workflow registration requires id. Received: ${JSON.stringify(data)}

What it means

Dev-server validation error from WorkflowHandler.validate: a workflow resource was registered without an `id`. The id (the workflow name passed to createWorkflow) is the key under which the dev server tracks the workflow and its steps for hot-reload; registration without it is rejected.

Source

Thrown at packages/core/utils/src/dev-server/handlers/workflow-handler.ts:20

  ResourceEntry,
  ResourceTypeHandler,
  WorkflowResourceData,
} from "../types"

export class WorkflowHandler
  implements ResourceTypeHandler<WorkflowResourceData>
{
  readonly type = "workflow"

  validate(data: WorkflowResourceData): void {
    if (!data.sourcePath) {
      throw new Error(
        `Workflow registration requires sourcePath. Received: ${JSON.stringify(
          data
        )}`
      )
    }

    if (!data.id) {
      throw new Error(
        `Workflow registration requires id. Received: ${JSON.stringify(data)}`
      )
    }
  }

  resolveSourcePath(data: WorkflowResourceData): string {
    return data.sourcePath
  }

  createEntry(data: WorkflowResourceData): ResourceEntry {
    return {
      id: data.id,
      workflowId: data.id,
    }
  }

View on GitHub (pinned to 5e06e544a2)

Solutions

Include the workflow's id — the same unique string given to createWorkflow — in the registration data.
Assert the id is a non-empty string before registering.
Keep the id consistent with the workflowId referenced by any step registrations so the inverse registry links them.

Example fix

// before
registerDevServerResource({ type: 'workflow', sourcePath })

// after
registerDevServerResource({ type: 'workflow', id: 'cart-workflow', sourcePath })

Defensive patterns

Strategy: validation

Validate before calling

if (!data.id) throw new Error(`Workflow registration missing id: ${JSON.stringify(data)}`)

Type guard

function isWorkflowResourceData(d: unknown): d is WorkflowResourceData {
  return typeof (d as any)?.id === 'string' && typeof (d as any)?.sourcePath === 'string'
}

Prevention

Pass the exact createWorkflow id string into registration data.
Keep workflow ids in constants shared by workflow and step registrations.
Assert non-empty id before calling the dev server.

When it happens

Trigger: Registering a workflow with only { type: 'workflow', sourcePath } and no id; loaders deriving the id from a variable that is undefined; registering an anonymous/dynamically-created workflow that never received a name.

Common situations: Custom loaders auto-registering workflow files; refactors renaming workflow ids while registration reads a stale property; workflows created via factories where the generated id is not passed along.

Related errors

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