medusajs/medusa · error · Error

Workflow registration requires sourcePath. Received: ${JSON.

Error message

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

What it means

Dev-server validation error from WorkflowHandler.validate: a workflow resource was registered without `sourcePath`. The dev server watches the workflow's defining file to hot-reload it (and its steps) during development; without the path, registration is rejected.

Source

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

import {
  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
  }

View on GitHub (pinned to 5e06e544a2)

Solutions

Pass the absolute path of the workflow module file (fileURLToPath(import.meta.url) where the workflow is defined).
If registering from a manifest, store and forward each workflow's file path.
Check the derived path is non-empty before calling registration.

Example fix

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

// after
registerDevServerResource({
  type: 'workflow',
  id: 'cart-workflow',
  sourcePath: fileURLToPath(import.meta.url),
})

Defensive patterns

Strategy: validation

Validate before calling

import { fileURLToPath } from 'node:url'
const sourcePath = fileURLToPath(import.meta.url)
if (!sourcePath) throw new Error('sourcePath could not be derived')

Type guard

function hasSourcePath(d: unknown): d is { sourcePath: string } {
  return typeof (d as any)?.sourcePath === 'string' && (d as any).sourcePath.length > 0
}

Prevention

Derive sourcePath from import.meta.url inside the workflow module.
Store file paths in workflow manifests if you register centrally.
Assert the path is non-empty before registration.

When it happens

Trigger: Registering a workflow with { type: 'workflow', id } but no sourcePath; loaders that register workflows from a central manifest without the file location.

Common situations: Custom setups enumerating workflows from configuration; bundling or path-alias setups where deriving the real file path fails; refactors moving registration away from the workflow file.

Related errors

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