medusajs/medusa · error · Error

Actor ID is required when tracking an event with Posthog

Error message

Actor ID is required when tracking an event with Posthog

What it means

The Posthog provider requires an actor_id on every tracked event so it can attribute the event to a distinct user. `track` throws when `data.actor_id` is falsy.

Source

Thrown at packages/modules/providers/analytics-posthog/src/services/posthog-analytics.ts:45

    if (!options.posthogEventsKey) {
      throw new Error("Posthog API key is not set, but is required")
    }

    this.client_ = new PostHog(options.posthogEventsKey, {
      host: options.posthogHost || "https://eu.i.posthog.com",
    })
  }

  async track(data: ProviderTrackAnalyticsEventDTO): Promise<void> {
    if (!data.event) {
      throw new Error(
        "Event name is required when tracking an event with Posthog"
      )
    }

    if (!data.actor_id) {
      throw new Error(
        "Actor ID is required when tracking an event with Posthog"
      )
    }

    if (data.group?.id && !data.group?.type) {
      throw new Error(
        "Group type is required if passing group id when tracking an event with Posthog"
      )
    }

    this.client_.capture({
      event: data.event,
      distinctId: data.actor_id,
      properties: data.properties,
      groups: data.group?.id
        ? { [data.group.type!]: data.group.id }
        : undefined,
    })

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Include the actor id: `track({ event, actor_id: authUserId })`
2. For anonymous users, pass a session or device identifier as actor_id

Example fix

// before
await analytics.track({ event: 'cart_created' })
// after
await analytics.track({ event: 'cart_created', actor_id: authUser.id })

if (!dto.actor_id) {
  dto.actor_id = sessionId ?? 'anonymous'
}

const hasActor = (d: ProviderTrackAnalyticsEventDTO): boolean => Boolean(d.actor_id)

try { await provider.track(dto) } catch (e) { logger.warn(`analytics track failed: ${e.message}`) }

When it happens

Trigger: Calling `track({ event: 'page_view' })` without actor_id, e.g. for anonymous visitor events.

Common situations: Tracking anonymous/guest activity where no user id exists, or forgetting to include the authenticated user's id in custom analytics calls.

Related errors

• Event name is required when tracking an event with Posthog
• Group type is required if passing group id when tracking an
• Actor or group is required when identifying an entity with P
• Posthog API key is not set, but is required
• --paths must be a directory - ${additionalPath}

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