AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

resolving-ingestion-warnings

Diagnoses and resolves PostHog ingestion warnings — problems recorded while ingesting events (dropped events, rejected person merges, oversized payloads, invalid data). Use when a user asks why events are missing, dropped, or undercounted, why identify/alias calls don't work or accounts stay duplicated, why person or group properties aren't updating or profiles look inflated, why recordings have gaps, heatmaps are empty, LLM token counts are missing, why cookieless events vanish, or whenever the `ingestion_warning` health check fires. Explains severity triage (error = dropped, warning = modified, info = intentional) and routes all warning types — size limits and enrichment, merges and distinct IDs, high-volume distinct IDs, `$process_person_profile`, timestamps, cookieless, heatmaps, transformations, session replay — to per-issue reference files with code-level causes and per-SDK fixes.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--resolving-ingestion-warnings at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 17

references/fixing-invalid-distinct-ids.md

Fixing the invalid distinct ID warnings

Both warnings are the same bug class: something that isn't a user identifier reached the distinct ID argument. The value's shape decides which warning fires:

| Type | Severity | The junk value | What happened | | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cannot_merge_with_illegal_distinct_id | warning | A blocklisted placeholder: undefined, null, NaN, [object Object], true, false, anonymous, guest, distinct_id, … | The identify/alias merge was refused — silently; the SDK call returned success. (If it weren't, every user hitting the same bug would merge into one giant "undefined" person) | | skipping_event_invalid_distinct_id | error | Anything over 400 characters — a JWT, a serialized object, a URL, a concatenation bug | The event was dropped entirely. Every event sent with that value is silently lost until fixed |

What it means in your code

  • posthog.identify(user.id) where user is not yet loaded → identify(undefined) → "undefined".
  • posthog.alias(String(session.userId)) with a missing field → "undefined" / "null"; an object passed where a string was expected → "[object Object]".
  • A token or payload flowing into the ID argument (dots and base64 → a JWT; braces → serialized JSON).
  • A hardcoded fallback like "anonymous" or "guest" for logged-out users — don't; PostHog already handles anonymous users with its own IDs.

Diagnose

  1. Query the warnings with posthog:execute-sql: SELECT timestamp, details FROM system.ingestion_warnings WHERE type IN ('cannot_merge_with_illegal_distinct_id', 'skipping_event_invalid_distinct_id') AND timestamp > now() - INTERVAL 7 DAY ORDER BY timestamp DESC LIMIT 20 (narrow to a single type to isolate one variant). The details JSON does most of the work: illegalDistinctId shows the placeholder (plus otherDistinctId, the real user it tried to link); the oversized variant shows the truncated distinctId and its length. The value's shape names the bug.
  2. Find the callsite: grep the app for identify(, alias(, and capture( with an explicit distinctId — and trace where the argument can be undefined (typically a race with auth state) or receive a token/object.

Fix

Guard every call so only a real, stable user identifier can reach the ID argument:

if (user?.id) {
  posthog.identify(user.id)
}
  • Call identify after authentication resolves (auth callback/effect), not on page load.
  • Never use fallback IDs for logged-out users — leave them anonymous; PostHog links the sessions when identify eventually runs.
  • Type the helper so objects and tokens can't be passed as the ID.

Verify

Re-run the login/affected flow, re-query system.ingestion_warnings with posthog:execute-sql (filter type IN ('cannot_merge_with_illegal_distinct_id', 'skipping_event_invalid_distinct_id'), timestamp after your fix) — no new occurrences of either type — and confirm events arrive under the correct persons.

Related