mongo-ai/posthog-event-diagnosis

Event diagnosis workflow

Before you diagnose: fetch live docs

1. Run docs-search("event ingestion troubleshooting {specific symptom}")
2. If SDK-specific: run Context7 query-docs for that SDK's capture/send reference
3. If potential known bug: run gh search issues on the relevant SDK repo
4. Use the fetched docs as your primary reference — NOT the steps below

The steps below are a diagnostic FRAMEWORK (what questions to ask, in what order). The docs responses are the CONTENT (current answers, version requirements, config details).

Goal

Determine whether the event problem is caused by:

• no capture
• wrong project / wrong region / wrong token
• ad blocker / proxy gap
• filtering / transformation
• ingestion issue
• duplicate capture logic
• downstream destination / pipeline issue

Step 1: Verify evidence exists

Query recent events for the distinct ID and, if known, event name.

SELECT event, timestamp, properties.$lib, properties.$lib_version, properties
FROM events
WHERE distinct_id = '{distinct_id}'
ORDER BY timestamp DESC
LIMIT 50;

If there are no events at all:

• suspect install/config issue
• verify token type confusion:
  • project token for capture
  • personal API key for admin/API access

Step 2: Check library and host clues

Look for:

• $lib
• $lib_version
• region / host mismatch clues in docs and ticket details
• browser vs backend source differences

Step 3: Check ad-blocker / reverse-proxy likelihood

If issue is browser-side and events are missing or intermittent:

• run docs-search("reverse proxy setup PostHog ad blocker")
• use the returned guidance for current proxy recommendations
• determine whether they use direct PostHog domains or a reverse proxy

Step 4: Check ingestion warnings and pipeline interference

SELECT event, timestamp, properties
FROM events
WHERE event = '$ingestion_warning'
ORDER BY timestamp DESC
LIMIT 20;

Also inspect functions / transformations / filter-out logic when relevant.

Step 5: Check duplicates

If duplicates are reported:

SELECT uuid, event, timestamp, distinct_id, properties
FROM events
WHERE event = '{event_name}'
  AND distinct_id = '{distinct_id}'
ORDER BY timestamp DESC
LIMIT 100;

Determine whether duplicates are:

• true duplicate capture
• multi-source intentional capture
• missing UUID/idempotency behavior
• frontend+backend double-send

Step 6: Check destination / CDP issues

If complaint is "it reached PostHog but not destination":

• inspect destination config
• inspect logs / errors
• determine whether the fault is pre-destination, transform-stage, or delivery-stage
• defer to posthog-pipeline-diagnosis if needed

Step 7: Search known issues

Search GitHub with at least 2 variants:

• gh search issues --repo PostHog/{sdk-repo} "{symptom}"
• gh search issues --repo PostHog/{sdk-repo} "event {specific issue}"

Common resolution patterns

• No events anywhere -> install/config issue
• Web-only gaps -> ad blocker / CSP / no reverse proxy
• Some events but not target event -> app logic or transformation/filter
• Duplicates -> multiple captures or missing idempotency/UUID strategy
• PostHog has event but destination doesn't -> destination/config/log issue