mongo-ai/posthog-survey-diagnosis

Survey diagnosis workflow

Before you diagnose: fetch live docs

1. Run docs-search("survey troubleshooting {specific symptom}")
2. If SDK-specific: run Context7 query-docs for that SDK's survey API reference
3. If potential known bug: run gh search issues --repo PostHog/posthog-js "survey {symptom}"
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 survey problem is caused by:

• survey not enabled or still in draft
• targeting conditions not matching the user
• display conditions or URL targeting mismatch
• SDK version too old for survey support
• API-mode survey not sending responses correctly
• ad blocker / reverse proxy blocking survey assets
• rate limiting or repeat display suppression
• known product bug

Step 1: Verify survey exists and is active

Use survey tools to confirm:

• survey exists
• survey status (draft / running / complete / archived)
• targeting rules
• display conditions

Step 2: Check survey response evidence

SELECT event, timestamp, distinct_id, properties.$survey_id, properties.$survey_response
FROM events
WHERE event = 'survey sent'
  AND properties.$survey_id = '{survey_id}'
ORDER BY timestamp DESC
LIMIT 50;

If no responses exist:

• check if the survey was ever shown (survey shown event)
• check if the user matches targeting

SELECT event, timestamp, distinct_id
FROM events
WHERE event IN ('survey shown', 'survey sent', 'survey dismissed')
  AND properties.$survey_id = '{survey_id}'
ORDER BY timestamp DESC
LIMIT 50;

Step 3: Check targeting and display conditions

If the survey is not appearing for a user:

• verify person properties match targeting conditions
• verify URL targeting matches the page the user is on
• check whether the user has already seen/dismissed the survey (repeat suppression)
• check survey opt-in config if relevant (fetch from docs)

Step 4: Check SDK version

Query SDK version:

SELECT properties.$lib, properties.$lib_version, count()
FROM events
WHERE distinct_id = '{distinct_id}'
  AND timestamp > now() - interval 7 day
GROUP BY properties.$lib, properties.$lib_version
ORDER BY count() DESC;

Run docs-search("survey minimum SDK version requirements") to get current minimum version — do NOT hardcode version numbers.

Step 5: API-mode surveys

If the survey uses API mode (no popup):

• run docs-search("survey API mode integration") for current API guidance
• verify the app is calling the surveys API correctly
• verify response events are being sent with correct survey ID
• check whether survey sent events have the expected shape

Step 6: Search known issues

Search GitHub with at least 2 variants:

• gh search issues --repo PostHog/posthog-js "survey {symptom}"
• gh search issues --repo PostHog/posthog "survey {symptom}"

Common resolution patterns

• Survey not showing -> draft status, targeting mismatch, URL condition, or repeat suppression
• Survey showing but responses not recorded -> API-mode integration issue or event shape problem
• Survey showing to wrong users -> targeting condition misconfiguration
• Survey assets blocked -> ad blocker or CSP blocking PostHog domains