/debugging-surveys

name: debugging-surveys
description: >-
  Diagnose PostHog Surveys configuration and responses across all five SDKs
  (web/posthog-js, iOS, Android, Flutter, React Native). Use whenever a Surveys
  support ticket is pasted ("survey not showing", "fewer responses than expected",
  "responses disappeared", "responses are incomplete", "only the first question was
  answered", "the user says they didn't mean to submit", "survey shows on wrong platform"),
  or when diagnosing why a survey does or doesn't display. Covers the eligibility pipeline, how a response actually gets
  stored (partial responses, branching, optional questions, auto-submit), cross-SDK feature
  parity, the known-cause catalog, read-only diagnostic queries, staff access, and the
  customer-reply style guide.

Debugging surveys

PostHog Surveys is a no-code in-app form builder. A customer creates a survey in the PostHog UI; it must then be evaluated and rendered by whichever SDK their app runs. **Most "survey not showing" tickets are eligibility problems, not rendering bugs** — the SDK correctly decided the user is not eligible, and the job is to find _which_ gate failed and _why_.

Access requirements

Use PostHog MCP tools or the survey API to inspect survey configuration and responses. A checkout of the PostHog repository is not required for these diagnostic steps.

Cross-SDK feature parity (check this FIRST)

A large class of tickets is "customer expects a feature their platform doesn't support." Confirm the survey's `lib` / the customer's platform before anything else, then consult this table. Verified against the SDK source — re-verify if it's been months, the gaps get filled over time.

| Feature | Web (posthog-js) | iOS | Android | Flutter | React Native | | -------------------------------- | ------------------------------- | ----------------------------------------- | ---------------------------------- | ---------------------------------- | --------------------------------- | | Rendering | DOM + shadow root | Native SwiftUI (`SurveysWindow`) | **No built-in UI** — delegate only | Dart widgets (`SurveyBottomSheet`) | RN components (`SurveyModal`) | | Event-based triggers | yes (since 1.137.0, 2024-06-05) | yes | yes | yes (native side) | yes | | URL / screen targeting | yes | decoded but **NOT evaluated** (`// TODO`) | decoded but **NOT evaluated** | **NOT evaluated** (native gap) | **explicitly excluded** in filter | | Feature-flag / cohort targeting | yes | yes | yes | yes (native side) | yes | | `seenSurveyWaitPeriodInDays` | yes | yes | yes | yes (native side) | yes (≥ 4.81.5) | | `surveyPopupDelaySeconds` | yes | **not implemented** | **not implemented** | **not implemented** | **not implemented** (TODO) | | `enable_partial_responses` | yes (≥ 1.240.0) | **no** | **no** | **no** | **no** | | `skipSubmitButton` (auto-submit) | yes (≥ 1.244.0) | **no** | **no** | **no** | **no** |

The last two rows are per the editor's own help text ("Doesn't work with the mobile SDKs for now" / "Not available for the mobile SDKs at the moment") rather than a per-SDK source audit.

Consequences worth memorizing:

• **`surveyPopupDelaySeconds` is web-only.** If a mobile ticket blames the delay, it's a red herring.
• **Partial responses and auto-submit are web-only too.** On mobile a survey always stores one response at the end, and a rating tap never self-submits. Don't carry a web diagnosis onto a mobile ticket.
• **URL targeting is effectively web-only.** Mobile SDKs decode the field but never enforce it; React Native filters those surveys out entirely. A mobile survey with a URL condition behaves as "no URL condition" (mobile/flutter) or "never shows" (RN).
• **Android ships no survey UI.** The app (or the Flutter plugin) must provide a `PostHogSurveysDelegate`. "Survey never renders on Android" is often a missing delegate, not a PostHog bug.
• **Flutter is hybrid:** triggering/eligibility runs in the native iOS/Android layer; rendering is Dart (`SurveyService.showSurvey` → `showModalBottomSheet`). It does _not_ "just call native" for UI. So a Flutter rendering bug lives in Dart; a Flutter eligibility bug lives in native.
• **React Native enforces the wait period from 4.81.5.** Older versions skip the check, so on those versions don't blame the wait period.

For a deeper version-by-version capability audit, see the `survey-sdk-audit` skill if available.

How a survey actually gets shown (the web eligibility pipeline)

The web SDK is the most complex and the most common in tickets. Mental model from `packages/browser/src/extensions/surveys.tsx` (`checkSurveyEligibility`) — checks run in order, first failure wins:

1. `isSurveyRunning` — has `start_date`, no `end_date`. 2. survey `type` is in-app (Popover / Widget / API). 3. `linked_flag_key` enabled (if set). 4. `targeting_flag_key` enabled (if set) — customer-defined property targeting. 5. `_internalFlagCheckSatisfied` — the auto-generated internal