medusajs/medusa · error · Error

Actor or group is required when identifying an entity with P

Error message

Actor or group is required when identifying an entity with Posthog

What it means

The Posthog provider's `identify` method must know what to identify: either a group (id+type) or an actor (distinct id). With neither present it throws because there is nothing to attach the properties to.

Source

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

        : undefined,
    })
  }

  async identify(data: ProviderIdentifyAnalyticsEventDTO): Promise<void> {
    if ("group" in data) {
      this.client_.groupIdentify({
        groupKey: data.group.id!,
        groupType: data.group.type!,
        properties: data.properties,
        distinctId: data.actor_id,
      })
    } else if (data.actor_id) {
      this.client_.identify({
        distinctId: data.actor_id,
        properties: data.properties,
      })
    } else {
      throw new Error(
        "Actor or group is required when identifying an entity with Posthog"
      )
    }
  }

  async shutdown() {
    await this.client_.shutdown()
  }
}

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Pass actor_id for user identification: `identify({ actor_id: userId, properties })`
2. For group identification pass a full group `{ id, type }`
3. Skip the identify call when neither id is available

Example fix

// before
await analytics.identify({ properties: { plan: 'pro' } })
// after
await analytics.identify({ actor_id: userId, properties: { plan: 'pro' } })

if (!data.actor_id && !data.group?.id) {
  logger.warn('identify skipped: no actor or group')
  return
}

const isIdentifiable = (d: ProviderIdentifyAnalyticsEventDTO): boolean => Boolean(d.actor_id || d.group?.id)

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

When it happens

Trigger: Calling `identify({ properties: {...} })` with no group and no actor_id, typically when the payload is built conditionally and both branches were skipped.

Common situations: Calling identify for a system/background entity, or a DTO assembled from optional request context where both ids are undefined.

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
• 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/ff62d047485d03f2. Report an issue: GitHub.