> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getflowpilot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Cross-cutting issues that span the dashboard and the SDK, and where to look first.

This page covers problems that span the dashboard and the SDK together. For issues that live entirely inside an SDK (crashes, configuration, error codes), see troubleshooting for [iOS](/ios-sdk/troubleshooting) or [Expo](/expo-sdk/troubleshooting).

## The flow looks different on device than in the editor preview

<AccordionGroup>
  <Accordion title="The editor preview is an approximation">
    The editor preview renders an approximation of the flow, not the SDK runtime on device. Some animations, transitions, and layout edge cases differ on device. Use [Live mirror](/editor/preview-and-live-mirror) to stream the editor to a real device for accurate QA.
  </Accordion>

  <Accordion title="Custom components render as placeholders in the editor">
    A custom component shows a placeholder shell in the editor and only renders your real native view on device, once registered. If it is blank on device, confirm you called `registerCustomComponent` with a matching key and version. See custom components for [iOS](/ios-sdk/custom-components) or [Expo](/expo-sdk/custom-components).
  </Accordion>

  <Accordion title="Fonts are not registered on device">
    Custom fonts must be available to the SDK. If text falls back to the system font on device, check the font is uploaded in the dashboard and that the resolve response lists it. See [Custom fonts](/dashboard/custom-fonts).
  </Accordion>

  <Accordion title="Persistent zone transitions behave differently">
    The iOS SDK collapses zone transition modes: `crossfade` and `reflow` animate, while `persistent` and `participate` stay fixed. A transition that looks distinct in the editor may map to the same behavior on device. See [Persistent UI zones](/editor/zones).
  </Accordion>
</AccordionGroup>

## Events are not showing up in analytics

<AccordionGroup>
  <Accordion title="The flow version is out of scope">
    The events endpoint drops events whose `flow_version_id` does not reference a real flow version in the same app. Hand-crafted or stale payloads are rejected and counted in `rejected`. Let the SDK send events; it always uses a real version ID. See [SDK REST API](/reference/sdk-rest-api).
  </Accordion>

  <Accordion title="The app_id does not match the URL">
    On the events endpoint the `app_id` from the URL is authoritative. An event whose body carries a different `app_id` is rejected. Confirm the SDK is configured with the correct API key and app.
  </Accordion>

  <Accordion title="Analytics is asynchronous">
    Events are buffered and written in batches, so they do not appear instantly. Allow a short delay before checking the dashboard.
  </Accordion>

  <Accordion title="You expected a resolve_no_flow event from the SDK">
    `resolve_no_flow` is recorded server-side by the backend, not emitted by the SDKs. You will not see it in the SDK analytics callback. See [Event taxonomy](/reference/event-taxonomy).
  </Accordion>
</AccordionGroup>

## Audience targeting never matches

<AccordionGroup>
  <Accordion title="Attribute names must match the filter property names">
    A condition matches an attribute by exact property name. If your filter targets `country` but the SDK sends `region`, it never matches. Send the attributes your filter expects. See [Audience targeting](/dashboard/audience-targeting).
  </Accordion>

  <Accordion title="Dotted property names (app.version) need care">
    The SDK sends some attributes as flat dotted keys (for example `app.version`, `app.build`). Filter property names must line up with how the value is actually sent. If a version filter never matches, verify the exact key the SDK provides against the filter property. See [Variables and context](/ios-sdk/variables-and-context).
  </Accordion>

  <Accordion title="The platform is not in the placement">
    A placement gates on platform (`ios`, `android`, `web`). If the placement does not list `ios`, an iOS resolve returns no flow regardless of the audience filter. See [Placements](/dashboard/placements).
  </Accordion>

  <Accordion title="Match mode is all vs any">
    A filter with `match: all` requires every condition to pass; `match: any` requires one. A single failing condition under `all` blocks the whole filter.
  </Accordion>
</AccordionGroup>

## Published changes are not appearing on device

<AccordionGroup>
  <Accordion title="The placement was not repointed">
    Publishing creates a new immutable flow version but does not change which version a placement serves. After publishing, attach the new version to the placement (set it as the default). See [Publishing](/editor/publishing).
  </Accordion>

  <Accordion title="The cached flow is still fresh">
    The SDK caches a resolved flow for `cache_ttl_seconds` (300 seconds by default). A repointed placement can take until the cache expires to appear on a device that already resolved. See [Caching](/ios-sdk/caching).
  </Accordion>

  <Accordion title="You edited the draft but did not publish">
    Drafts are never served. Only published versions are. Save and publish, then attach. See [Publishing](/editor/publishing).
  </Accordion>
</AccordionGroup>

## Nothing shows for a placement

<AccordionGroup>
  <Accordion title="No flow matched (resolve returned null)">
    A resolve can match no flow: the platform is excluded, the audience filter excludes the user, the placement is paused, or no published flow is attached. The backend records a `resolve_no_flow` event. Check the placement's platforms, filter, status, and default flow version. See [Placements](/dashboard/placements).
  </Accordion>

  <Accordion title="The SDK could not present">
    If a resolve fails (network, timeout, or no flow) the SDK falls back per its presentation path and may surface an error rather than UI. See troubleshooting for [iOS](/ios-sdk/troubleshooting) or [Expo](/expo-sdk/troubleshooting).
  </Accordion>
</AccordionGroup>

## Related pages

* [iOS SDK troubleshooting](/ios-sdk/troubleshooting)
* [Expo SDK troubleshooting](/expo-sdk/troubleshooting)
* [Preview and live mirror](/editor/preview-and-live-mirror)
* [Audience targeting](/dashboard/audience-targeting)