medusajs/medusa · error · Error

Job registration requires id. Received: ${JSON.stringify(dat

Error message

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

What it means

Dev-server validation error: when registering a scheduled job resource with the Medusa development server, the resource data carried no `id`. JobHandler.validate throws before the resource is tracked, so hot-reload registration of the job is aborted.

Source

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

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
        )}`
      )

View on GitHub (pinned to 5e06e544a2)

Solutions

Ensure the job registration data includes a stable, unique id (commonly the job scheduler name).
If ids are derived from config, check for undefined before registering (data.id ?? throw).
Confirm you are registering with type 'job' and constructing JobResourceData with all required fields (id, sourcePath, config.name).

Example fix

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

// after
registerDevServerResource({ type: 'job', id: config.name, sourcePath, config })

Defensive patterns

Strategy: validation

Validate before calling

if (!data.id) throw new Error(`Missing job id in ${data.sourcePath ?? 'unknown file'}`)

Type guard

function isJobResourceData(d: unknown): d is JobResourceData {
  return !!d && typeof (d as any).id === 'string' && !!(d as any).sourcePath && !!(d as any).config?.name
}

Prevention

Default job id to config.name when constructing registration data.
Centralize resource-data construction in one factory that asserts required fields.
Run the dev server locally so registration errors surface at save time.

When it happens

Trigger: Calling the dev-server registration API for a job (type: 'job') with a payload missing the id field; a job file whose registration metadata is built dynamically and the id ends up undefined.

Common situations: Writing custom scheduled jobs in a Medusa project and the loader passes an incomplete config; renaming the id field in job config while the registration code still reads the old key; frameworks/plugins that auto-register jobs from a glob and encounter a file exporting no id.

Related errors

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