medusajs/medusa · error · Error

Job registration requires sourcePath. Received: ${JSON.strin

Error message

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

What it means

Dev-server validation error from JobHandler.validate: a job resource was registered without `sourcePath`, the filesystem path of the file that defines the job. The dev server needs the source path to watch the file and hot-reload the job when it changes, so registration is rejected.

Source

Thrown at packages/core/utils/src/dev-server/handlers/job-handler.ts:14

import { JobResourceData, ResourceEntry, ResourceTypeHandler } from "../types"

export class JobHandler implements ResourceTypeHandler<JobResourceData> {
  readonly type = "job"

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

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

    if (!data.config?.name) {
      throw new Error(
        `Job registration requires config.name. Received: ${JSON.stringify(
          data
        )}`
      )
    }
  }

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

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Pass the absolute path of the job module file, typically derived with import.meta.url (fileURLToPath(import.meta.url)).
2. If registering from a central place, thread the originating file path through your loader into the registration call.
3. Verify the value is a non-empty string right before registering.

Example fix

// before
registerDevServerResource({ type: 'job', id, config })

// after
import { fileURLToPath } from 'node:url'
registerDevServerResource({
  type: 'job',
  id: config.name,
  sourcePath: fileURLToPath(import.meta.url),
  config,
})

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

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

When it happens

Trigger: Registering a job with { type: 'job', id, config } but omitting sourcePath; building registration data from import.meta.url incorrectly (e.g. stripping the file URL to an empty string); plugin loaders that register jobs without forwarding the originating file path.

Common situations: Custom plugin setups where jobs are collected in an index and registered in a loop losing per-file paths; refactors that move registration away from the job file; path derivation that returns undefined on Windows or when bundled.

Related errors

• Job registration requires id. Received: ${JSON.stringify(dat
• Job registration requires config.name. Received: ${JSON.stri
• Step registration requires either sourcePath or workflowId.
• Subscriber registration requires sourcePath. Received: ${JSO
• Workflow registration requires sourcePath. Received: ${JSON.

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