medusajs/medusa · error · Error

Subscriber registration requires events. Received: ${JSON.st

Error message

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

What it means

Dev-server validation error from SubscriberHandler.validate: a subscriber resource was registered without an `events` field. The dev server needs the list of event names the subscriber listens to in order to wire tracking; a registration without events is rejected.

Source

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

      )
    }

    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(
        `Subscriber registration requires events to be an array. Received: ${JSON.stringify(
          data
        )}`
      )
    }
  }

  resolveSourcePath(data: SubscriberResourceData): string {

View on GitHub (pinned to 5e06e544a2)

Solutions

Add the events array listing every event name the subscriber handles, e.g. ['order.placed', 'order.canceled'].
If events are inferred from the subscriber implementation, compute the list and pass it explicitly at registration time.
Verify event names are strings and spelled exactly as emitted by the event bus.

Example fix

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

// after
registerDevServerResource({
  type: 'subscriber', id, sourcePath, subscriberId,
  events: ['order.placed'],
})

Defensive patterns

Strategy: validation

Validate before calling

if (!data.events) throw new Error(`Subscriber ${data.id} must declare events`)

Type guard

function hasEvents(d: unknown): d is { events: unknown[] } {
  return Array.isArray((d as any)?.events) && (d as any).events.length > 0
}

Prevention

Declare the event list explicitly even when the implementation implies it.
Reuse constants for event names to avoid typos drifting between emitter and subscriber.
Validate the full registration object in one guard before calling the dev server.

When it happens

Trigger: Registering a subscriber with { type: 'subscriber', id, sourcePath, subscriberId } and no events; building registration data from a subscriber config that omits the events array (e.g. a handler-based subscriber where events are implied).

Common situations: Subscribers whose event list is derived from the class (EVENT handers) rather than declared in config, while the loader still expects an explicit array; refactors dropping the field; plugin metadata missing the events key.

Related errors

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