medusajs/medusa · error · Error

Subscriber registration requires subscriberId. Received: ${J

Error message

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

What it means

Dev-server validation error from SubscriberHandler.validate: a subscriber resource was registered without `subscriberId`. The subscriberId identifies the concrete subscriber handler (distinct from the registration id) and is required for the dev server to track the right handler for hot-reload.

Source

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

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

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

    if (!Array.isArray(data.events)) {
      throw new Error(

View on GitHub (pinned to 5e06e544a2)

Solutions

Include subscriberId in the registration data — typically the constructor-based or exported subscriber identifier.
If the value lives in your subscriber config under another key, map it explicitly to subscriberId before registering.
Add a dev-time assertion so a missing subscriberId fails fast with your own clearer message.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

if (!data.subscriberId) throw new Error(`Subscriber ${data.id} missing subscriberId`)

Type guard

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

Prevention

Map your internal handler key to subscriberId explicitly at registration.
Type the registration payload so missing fields fail at compile time.
Keep a checklist of required subscriber fields: id, sourcePath, subscriberId, events.

When it happens

Trigger: Registering a subscriber where the subscriberId field is missing or undefined — e.g. passing only the module id and events; constructing registration data from an object that stores the handler's key under a different name (like `handlerId`).

Common situations: Custom subscriber loaders copying fields selectively and dropping subscriberId; refactors renaming the property; subscribers defined via a factory where the generated id is not propagated to the registration.

Related errors

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