{"record":{"id":"736bb9f5f374a056","repo":"medusajs/medusa","slug":"actor-id-is-required-when-tracking-an-event-with-p","errorCode":null,"errorMessage":"Actor ID is required when tracking an event with Posthog","messagePattern":"Actor ID is required when tracking an event with Posthog","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/modules/providers/analytics-posthog/src/services/posthog-analytics.ts","lineNumber":45,"sourceCode":"\n    if (!options.posthogEventsKey) {\n      throw new Error(\"Posthog API key is not set, but is required\")\n    }\n\n    this.client_ = new PostHog(options.posthogEventsKey, {\n      host: options.posthogHost || \"https://eu.i.posthog.com\",\n    })\n  }\n\n  async track(data: ProviderTrackAnalyticsEventDTO): Promise<void> {\n    if (!data.event) {\n      throw new Error(\n        \"Event name is required when tracking an event with Posthog\"\n      )\n    }\n\n    if (!data.actor_id) {\n      throw new Error(\n        \"Actor ID is required when tracking an event with Posthog\"\n      )\n    }\n\n    if (data.group?.id && !data.group?.type) {\n      throw new Error(\n        \"Group type is required if passing group id when tracking an event with Posthog\"\n      )\n    }\n\n    this.client_.capture({\n      event: data.event,\n      distinctId: data.actor_id,\n      properties: data.properties,\n      groups: data.group?.id\n        ? { [data.group.type!]: data.group.id }\n        : undefined,\n    })","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/modules/providers/analytics-posthog/src/services/posthog-analytics.ts#L27-L63","documentation":"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.","triggerScenarios":"Calling `track({ event: 'page_view' })` without actor_id, e.g. for anonymous visitor events.","commonSituations":"Tracking anonymous/guest activity where no user id exists, or forgetting to include the authenticated user's id in custom analytics calls.","solutions":["Include the actor id: `track({ event, actor_id: authUserId })`","For anonymous users, pass a session or device identifier as actor_id"],"exampleFix":"// before\nawait analytics.track({ event: 'cart_created' })\n// after\nawait analytics.track({ event: 'cart_created', actor_id: authUser.id })","handlingStrategy":"validation","validationCode":"if (!dto.actor_id) {\n  dto.actor_id = sessionId ?? 'anonymous'\n}","typeGuard":"const hasActor = (d: ProviderTrackAnalyticsEventDTO): boolean => Boolean(d.actor_id)","tryCatchPattern":"try { await provider.track(dto) } catch (e) { logger.warn(`analytics track failed: ${e.message}`) }","preventionTips":["Always derive actor_id from the authenticated request context","Fall back to a session/device id for anonymous traffic"],"tags":["posthog","analytics","validation"],"backgroundTag":"required-field-missing","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}