SKILL.md · 24000
|
| invalid_group_set | $groupidentify dropped: $group_set wasn't a plain object (a string, number, boolean, or array was sent) | details.receivedType names what was sent — string usually means the caller JSON-stringified the group properties before passing them; pass a plain object to the SDK's groupIdentify call. Omitting $group_set is fine (group upserts with no property changes) |
| invalid_process_person_profile | $process_person_profile wasn't boolean; the default (true) was used | Read references/fixing-process-person-profile-warnings.md — a stringified boolean silently opts back into person processing |
| invalid_event_when_process_person_profile_is_false | $identify/$create_alias/$merge_dangerously/$groupidentify dropped because the event disabled person processing | Read references/fixing-process-person-profile-warnings.md — identity events require person processing |
| event_dropped_person_processing_disabled | Intentional: person processing is off for the project, so $identify/$create_alias/$merge_dangerously/$groupidentify are dropped | Read references/fixing-process-person-profile-warnings.md — no payload fix exists; drop the identity calls or ask staff to re-enable person processing |
| event_dropped_too_old | Intentional: the event is older than the team's configured drop threshold | Read references/fixing-event-dropped-too-old.md — mind mobile SDKs: offline queues legitimately deliver days-old events; threshold changes are the user's call |
| cookieless_missing_timestamp / cookieless_timestamp_out_of_range / cookieless_missing_user_agent / cookieless_missing_ip / cookieless_missing_host | Cookieless-mode event dropped: a field required to compute the cookieless ID was missing or invalid | Read references/fixing-cookieless-warnings.md — the missing field identifies the broken layer; beware the silent variant where a server relay omits $ip and users collapse onto the server's IP |
| cookieless_team_disabled | Cookieless-mode event dropped: the SDK sent it in cookieless mode but cookieless tracking is off in the project settings | Read references/fixing-cookieless-warnings.md — enable Settings → Web analytics → Cookieless tracking, or remove cookieless_mode from the SDK config; no code fix needed |
| invalid_options | Event dropped by a capture v1 endpoint (/i/v1/analytics/events, /i/v1/ai/events): an event option had a value PostHog couldn't read | details.invalidOptions (when present) names the failed options. Send process_person_profile, cookieless_mode and disable_skew_correction as booleans (common forms such as "false", "no", "off" or 0 also work) and product_tour_id as a non-empty string (an integer also works) |
LLM analytics endpoints (event)
Emitted by capture for its two dedicated AI endpoints, /i/v0/ai (a single event per request, sent multipart) and /i/v0/ai/otel (OTLP traces). These reject at the edge, so the events never reach the pipeline and appear nowhere else. Read the path detail to tell the endpoints apart: it carries the request path, so /i/v0/ai or /i/v0/ai/otel.
| Type | What happened | Fix |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| invalid_ai_event | Event rejected: the name doesn't start with $ai_, or $ai_model is missing or not a string | Read references/fixing-ai-endpoint-rejections.md — usually ordinary analytics pointed at the AI endpoint |
| invalid_ai_payload | Request rejected: malformed multipart or OTLP body, or too many spans in one export | Read references/fixing-ai-endpoint-rejections.md — format, stage, and part details name which check failed |
| no_ai_spans_ingested | OTLP export accepted with a 200 but contained no AI spans, so nothing was ingested | Read references/fixing-ai-endpoint-rejections.md — instrumentation is emitting spans no AI provider convention matches |
| misrouted_event | An event whose name does not start with $ai_ reached the AI batch endpoint (/i/v1/ai/events); only that event was discarded, the rest of the batch landed | Read references/fixing-ai-endpoint-rejections.md — eventName names the offender; send it through the standard capture endpoint |
Heatmaps (event)
| Type | What happened | Fix |
| ------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| invalid_heatmap_data | $heatmap_data didn't parse; the heatmap portion was dropped (event survived) | Read references/fixing-invalid-heatmap-data.md — the whole payload failed to parse; event survived, heatmap data lost |
| rejecting_heatmap_data_with_invalid_url | Heatmap entry keyed by an invalid URL | Read references/fixing-invalid-heatmap-data.md — the entry key (page URL) was empty or not a string |
| rejecting_heatmap_data_with_invalid_items | Heatmap URL mapped to a non-array | Read references/fixing-invalid-heatmap-data.md — each URL key must map to an ARRAY of items |
Error tracking (event)
| Type | What happened | Fix |
| -------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| error_tracking_exception_processing_errors | A $exception event was ingested but symbolication hit errors | Read details.errors; usually missing/mismatched source maps — re-upload them for the release |
Quota (quota)
| Type | What happened | Fix |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| high_volume_distinct_id | One distinct ID sent more events than the per-project, per-distinct-ID rate limit allows. Capture kept the events but turned off person processing for them: they do not update person properties and land as personless events. Events bound for the main analytics lane also move to the overflow lane, so they can arrive out of order; historical and other lanes keep their destination. Nothing was dropped | details.distinctId names the hot ID when exactly one distinct ID in the batch was rate-limited; otherwise details.distinctIdCount gives the number of rate-limited distinct IDs, and details.count gives the affected events. A single ID that sends at this rate is almost never a real user: look for a hardcoded or shared fallback ID ("server", a tenant or org ID, a service account), a load test, or a retry loop. Give each real user its own distinct ID. For backend or system events that belong to no user, send a unique ID per event (for example a UUID) with $process_person_profile: false, not one shared ID. The limit is a platform limit, not a project setting |
Transformations (transformation)
| Type | What happened | Fix |
| --------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| event_dropped_by_transformation | A transformation the team configured dropped the event (intentional) | Read references/fixing-event-dropped-by-transformation.md — the details name the exact transformation; edits to it are the user's call |
Session replay (replay)
Two producers land in this category, and the source column tells them apart. source = 'capture' means capture rejected the request at the /s edge, so the batch reached nothing downstream and has no other trace; its path detail is /s or /s/. Anything else (plugin-server) came from the replay consumer, which had already accepted the batch. The first three rows below are the capture-stage ones.
| Type | What happened | Fix |
| ----------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| missing_session_id | The batch's first $snapshot carried no $session_id, so the whole request was rejected | Read references/fixing-capture-replay-rejections.md — usually session-id management the SDK isn't driving |
| invalid_session_id | $session_id was present but the wrong JSON type, over 70 chars, or outside [A-Za-z0-9-] | Read references/fixing-capture-replay-rejections.md — the reason detail names which rule broke; almost always a custom session id |
| missing_snapshot_data | An event in the batch had no $snapshot_data, or it wasn't an array or object | Read references/fixing-capture-replay-rejections.md — the reason detail separates absent from wrong-type; check for a rewriting proxy |
| replay_lib_version_too_old | Recording sent by an outdated posthog-js (1.x < 1.75) | Read [references/fixing-session-replay-warnings.md](references/fixing-session-replay-warnin