medusajs/medusa · critical · Error

Posthog API key is not set, but is required

Error message

Posthog API key is not set, but is required

What it means

The Posthog analytics provider module requires an events API key to be passed in its options. The provider constructor throws during module initialization when `posthogEventsKey` is missing, so the Medusa server fails at boot before serving any requests.

Source

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

  logger: Logger
}

export class PosthogAnalyticsService extends AbstractAnalyticsProviderService {
  static identifier = "analytics-posthog"
  protected config_: PosthogAnalyticsServiceOptions
  protected logger_: Logger
  protected client_: PostHog

  constructor(
    { logger }: InjectedDependencies,
    options: PosthogAnalyticsServiceOptions
  ) {
    super()
    this.config_ = options
    this.logger_ = logger

    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"
      )

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Set the posthogEventsKey option in medusa-config: `analyticsPosthogService: { resolve: '@medusajs/analytics-posthog', options: { posthogEventsKey: process.env.POSTHOG_EVENTS_KEY } }`
2. Verify the env var is present in the environment where Medusa boots (check .env loading and deployment secrets)
3. Only register the module when the key exists, or remove the module if you don't use Posthog

Example fix

// before
resolve: './src/modules/my-analytics',
options: {}
// after
resolve: '@medusajs/analytics-posthog',
options: { posthogEventsKey: process.env.POSTHOG_EVENTS_KEY }

const key = process.env.POSTHOG_EVENTS_KEY
if (!key) {
  throw new Error('POSTHOG_EVENTS_KEY is required when enabling the Posthog analytics module')
}

When it happens

Trigger: Registering the analytics-posthog module in medusa-config without a `posthogEventsKey` option (or with an empty/undefined env var used for it).

Common situations: Env var POSTHOG_API_KEY not set in the deployment environment, typo in the option name, or copying a config example that omits the key.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Event name is required when tracking an event with Posthog
• Actor ID 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
• Github clientId is required

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