What causes "Error tracking event for ${data.event}: ${error.message}" in medusajs/medusa?

Inspect the appended error.message to identify the provider failure (auth, network, payload)

medusajs/medusa · error · MedusaError

Error tracking event for ${data.event}: ${error.message}

Error message

Error tracking event for ${data.event}: ${error.message}

What it means

Thrown by the analytics module's track() when the configured analytics provider's track() call fails; the underlying provider error message is wrapped in a MedusaError of type UNEXPECTED_STATE. The module itself is a thin wrapper around a pluggable analytics provider, so this always indicates a provider-side failure (network, auth, payload).

Source

Thrown at packages/modules/analytics/src/services/analytics-service.ts:33

  constructor({ analyticsProviderService }: InjectedDependencies) {
    this.analyticsProviderService_ = analyticsProviderService
  }

  __hooks = {
    onApplicationShutdown: async () => {
      await this.analyticsProviderService_.shutdown()
    },
  }

  getProvider() {
    return this.analyticsProviderService_
  }

  async track(data: TrackAnalyticsEventDTO): Promise<void> {
    try {
      await this.analyticsProviderService_.track(data)
    } catch (error) {
      throw new MedusaError(
        MedusaError.Types.UNEXPECTED_STATE,
        `Error tracking event for ${data.event}: ${error.message}`
      )
    }
  }

  async identify(data: IdentifyAnalyticsEventDTO): Promise<void> {
    try {
      await this.analyticsProviderService_.identify(data)
    } catch (error) {
      throw new MedusaError(
        MedusaError.Types.UNEXPECTED_STATE,
        `Error identifying event for ${
          "group" in data ? data.group.id : data.actor_id
        }: ${error.message}`
      )
    }
  }

View on GitHub (pinned to 5e06e544a2)

Solutions

Inspect the appended error.message to identify the provider failure (auth, network, payload)
Verify the analytics provider credentials/config passed to the AnalyticsModule in medusa-config
If the failure is transient (rate limit/network), retry or make tracking non-fatal in your workflow
Check that the event payload matches the provider's expected schema

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await analyticsService.track({ event: 'order_placed', ... })
} catch (e) {
  if (e.type === 'unexpected_state' && /^Error tracking event/.test(e.message)) {
    logger.warn(`analytics track failed: ${e.message}`) // non-fatal
    return
  }
  throw e
}

Prevention

Treat analytics as non-fatal: wrap track calls so tracking outages don't break commerce flows
Monitor provider credential expiry and provider status pages
Validate event payloads against the provider schema in dev/test environments

When it happens

Trigger: Any workflow/step or internal call invoking analyticsModuleService.track(...) while the analytics provider (e.g. a third-party tracking API) errors — invalid credentials, unreachable endpoint, malformed event payload, or rate limiting.

Common situations: Analytics provider API key rotated/expired and not updated in module options; network egress blocked from the server; provider schema change rejecting the event payload.

Related errors

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