medusajs/medusa · error · Error

Job registration requires config.name. Received: ${JSON.stri

Error message

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

What it means

Dev-server validation error from JobHandler.validate: the job resource's config object is missing its `name` property (config?.name is falsy). The scheduler identifies a job by config.name, so a job registration without it cannot be scheduled or hot-reloaded and is rejected.

Source

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

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
  }

  createEntry(data: JobResourceData): ResourceEntry {
    return {
      id: data.id,
      config: data.config,
    }

View on GitHub (pinned to 5e06e544a2)

Solutions

Add a non-empty config.name to the job registration config (this is the identifier used by the scheduler).
Make sure config itself is an object and name is at config.name, not a sibling field.
Keep id and config.name consistent to avoid duplicate registrations of the same job under two identities.

Example fix

// before
registerDevServerResource({
  type: 'job', id: 'daily-report', sourcePath,
  config: { schedule: '0 1 * * *' }, // no name
})

// after
registerDevServerResource({
  type: 'job', id: 'daily-report', sourcePath,
  config: { name: 'daily-report', schedule: '0 1 * * *' },
})

Defensive patterns

Strategy: validation

Validate before calling

if (!config?.name) throw new Error(`Job config missing name: ${JSON.stringify(config)}`)

Type guard

function hasJobName(c: unknown): c is { name: string } {
  return typeof (c as any)?.name === 'string' && (c as any).name.length > 0
}

Prevention

Use config.name as the canonical job identifier and reuse it for id.
Type your job configs so name is required at compile time.
Validate configs at load time in one place rather than per registration.

When it happens

Trigger: Registering a job whose config only has a schedule (e.g. { schedule: '* * * * *' }) but no name; passing the whole module export as config when the name lives one level deeper; typo like `config: { Name: ... } }`.

Common situations: Writing a custom scheduled job config object and forgetting the name key; Medusa job configs require name plus schedule — omitting name commonly happens when copying a workflow-style config; config built from user input where name is optional and left empty.

Related errors

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