medusajs/medusa · error · Error

Subscriber registration requires id. Received: ${JSON.string

Error message

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

What it means

Dev-server validation error from SubscriberHandler.validate: a subscriber resource was registered without an `id`. The id identifies the subscriber for tracking and hot-reload, so registration is rejected before the subscriber is watched.

Source

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

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

export class SubscriberHandler
  implements ResourceTypeHandler<SubscriberResourceData>
{
  readonly type = "subscriber"

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

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

    if (!data.subscriberId) {
      throw new Error(
        `Subscriber registration requires subscriberId. Received: ${JSON.stringify(
          data

View on GitHub (pinned to 5e06e544a2)

Solutions

Include a unique, stable id in the subscriber registration data.
If the id derives from a config value, default it explicitly (e.g. id = config.id ?? `${sourcePath}`) so it can never be undefined.
Ensure the full required set is present: id, sourcePath, subscriberId, events (array).

Example fix

// before
registerDevServerResource({ type: 'subscriber', sourcePath, subscriberId, events })

// after
registerDevServerResource({ type: 'subscriber', id: 'order-sub', sourcePath, subscriberId, events })

Defensive patterns

Strategy: validation

Validate before calling

if (!data.id) throw new Error(`Missing subscriber id: ${JSON.stringify(data)}`)

Type guard

function isSubscriberResourceData(d: unknown): d is SubscriberResourceData {
  const v = d as any
  return typeof v?.id === 'string' && typeof v?.sourcePath === 'string' && typeof v?.subscriberId === 'string' && Array.isArray(v?.events)
}

Prevention

Construct all subscriber registration data through one typed factory.
Default the registration id from the subscriber file path when no explicit id exists.
Fail fast in dev with your own validation before the dev server rejects it.

When it happens

Trigger: Calling subscriber registration with a payload lacking the id field; loaders that construct subscriber metadata from a config object whose id key is absent or undefined.

Common situations: Writing custom subscribers in a Medusa project and passing an incomplete registration object; refactor where the id property was renamed but registration still reads the old key; plugin auto-registration scanning subscriber files that export no id.

Related errors

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