medusajs/medusa · error · Error

Subscriber registration requires sourcePath. Received: ${JSO

Error message

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

What it means

Dev-server validation error from SubscriberHandler.validate: a subscriber resource was registered without `sourcePath`, the path of the file defining the subscriber. The dev server requires it to watch the file and hot-reload the subscriber when it changes; registration is therefore rejected.

Source

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

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

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

View on GitHub (pinned to 5e06e544a2)

Solutions

Pass the absolute path of the subscriber module file (fileURLToPath(import.meta.url) at the registration site).
Thread the file path through your loader so each subscriber registration carries its own path.
Assert sourcePath is a non-empty string right before registering.

Example fix

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

// after
registerDevServerResource({
  type: 'subscriber', id, subscriberId, events,
  sourcePath: fileURLToPath(import.meta.url),
})

Defensive patterns

Strategy: validation

Validate before calling

import { fileURLToPath } from 'node:url'
const sourcePath = fileURLToPath(import.meta.url)
if (!sourcePath) throw new Error('sourcePath could not be derived')

Type guard

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

Prevention

Derive sourcePath from import.meta.url at the registration site.
Forward file paths through loaders instead of registering from a central index.
Assert non-empty path before registering.

When it happens

Trigger: Registering a subscriber with { type: 'subscriber', id, subscriberId, events } but no sourcePath; loaders that register subscribers from a central index without forwarding the defining file's path.

Common situations: Plugins registering subscribers discovered by directory scanning where the path is dropped; path derivation from import.meta.url that breaks after bundling or on Windows.

Related errors

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