{"record":{"id":"f88c15157f60440a","repo":"medusajs/medusa","slug":"posthog-api-key-is-not-set-but-is-required","errorCode":null,"errorMessage":"Posthog API key is not set, but is required","messagePattern":"Posthog API key is not set, but is required","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/modules/providers/analytics-posthog/src/services/posthog-analytics.ts","lineNumber":29,"sourceCode":"  logger: Logger\n}\n\nexport class PosthogAnalyticsService extends AbstractAnalyticsProviderService {\n  static identifier = \"analytics-posthog\"\n  protected config_: PosthogAnalyticsServiceOptions\n  protected logger_: Logger\n  protected client_: PostHog\n\n  constructor(\n    { logger }: InjectedDependencies,\n    options: PosthogAnalyticsServiceOptions\n  ) {\n    super()\n    this.config_ = options\n    this.logger_ = logger\n\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      )","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/medusajs/medusa/blob/5e06e544a296b9033f20f71f11c559f81a0e5739/packages/modules/providers/analytics-posthog/src/services/posthog-analytics.ts#L11-L47","documentation":"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.","triggerScenarios":"Registering the analytics-posthog module in medusa-config without a `posthogEventsKey` option (or with an empty/undefined env var used for it).","commonSituations":"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.","solutions":["Set the posthogEventsKey option in medusa-config: `analyticsPosthogService: { resolve: '@medusajs/analytics-posthog', options: { posthogEventsKey: process.env.POSTHOG_EVENTS_KEY } }`","Verify the env var is present in the environment where Medusa boots (check .env loading and deployment secrets)","Only register the module when the key exists, or remove the module if you don't use Posthog"],"exampleFix":"// before\nresolve: './src/modules/my-analytics',\noptions: {}\n// after\nresolve: '@medusajs/analytics-posthog',\noptions: { posthogEventsKey: process.env.POSTHOG_EVENTS_KEY }","handlingStrategy":"validation","validationCode":"const key = process.env.POSTHOG_EVENTS_KEY\nif (!key) {\n  throw new Error('POSTHOG_EVENTS_KEY is required when enabling the Posthog analytics module')\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Fail fast in a config check script before boot","Keep all module option env vars in one documented list","Add a startup smoke test that boots the app in CI with required env vars set"],"tags":["posthog","analytics","module-config","startup"],"backgroundTag":"missing-env-var","analyzedSha":"5e06e544a296b9033f20f71f11c559f81a0e5739","analyzedAt":"2026-08-27T07:24:39.599Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}