medusajs/medusa · error · Error

Subscriber registration requires events to be an array. Rece

Error message

Subscriber registration requires events to be an array. Received: ${JSON.stringify(data)}

What it means

Dev-server validation error from SubscriberHandler.validate: the `events` field was provided but is not an Array (Array.isArray(data.events) is false). Subscribers must declare the event names they listen to as an array, so a string, object, or other non-array value is rejected.

Source

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

      )
    }

    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 {
    return data.sourcePath
  }

  createEntry(data: SubscriberResourceData): ResourceEntry {
    return {
      id: data.id,
      subscriberId: data.subscriberId,
      events: data.events,

View on GitHub (pinned to 5e06e544a2)

Solutions

Wrap single events in an array: events: ['order.placed'].
If your config accepts a scalar or list, normalize before registering: Array.isArray(events) ? events : [events].
Type the registration payload (SubscriberResourceData) so TypeScript rejects non-array events at compile time.

Example fix

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

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

Defensive patterns

Strategy: type-guard

Validate before calling

const events = Array.isArray(config.events) ? config.events : [config.events].filter(Boolean)

Type guard

function isEventArray(events: unknown): events is string[] {
  return Array.isArray(events) && events.every((e) => typeof e === 'string')
}

Prevention

Always declare events as an array, even for a single event.
Normalize config-sourced values (JSON/YAML) before registration.
Type the field as string[] in your own config types.

When it happens

Trigger: Registering a subscriber with events: 'order.placed' (a single string) instead of an array; events set to an object map like { 'order.placed': handler }; events set to a comma-joined string built by string concatenation.

Common situations: Loosely-typed config objects from JSON/YAML where a single event is written as a scalar; JS code paths where the type is never checked before registration.

Related errors

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