Guide or Survey not showing

A guide or survey that never appears usually fails one of five checks: the SDK isn't running on the page or in the app, the experience isn't published to the right project, the user doesn't match the targeting, the trigger never fires, or a limit or throttle blocks the display. Work through the checks in that order, because a broken SDK setup makes every other check impossible to evaluate.

This article assumes you know how to configure a guide or survey. If you need a refresher, review Setup and Targeting before proceeding. If the experience shows more often than you expect instead, go to Guide or Survey seen too often.

Debug with Preview mode and platform tools

Before you change any settings, use the tools that report which condition fails. They save you from guessing.

Web: Chrome extension and Preview mode

The Amplitude Chrome extension is the fastest way to diagnose a web guide or survey that doesn't show. Its Guides & Surveys tab reports:

• SDK setup: whether the SDK is installed, initialized, connected to an analytics SDK, and booted, plus the API key in Show config and the resolved user in Show user info.
• Trigger conditions: for every published guide and survey in the project, which conditions pass and which block the display, including built-in throttles, custom throttles, limits, page targeting, snooze, and user targeting.
• Forwarded events: every client-side event the SDK observes. Enter an event name and click Test Event to simulate it and confirm an event-based trigger fires.

The extension's Guides & Surveys tab doesn't update live, so wait for the page to finish loading before you read it.

Preview mode checks a single experience against a real page. The preview bar shows the Trigger, Limit, and Throttle conditions, where green means the condition passes and yellow means it blocks the display. From the preview bar you can also click Reset User History, toggle Ignore Throttle Limits, and manually trigger the event a trigger waits on. If the preview itself never appears, go to Troubleshooting preview mode, which covers window.postMessage failures and the Cross-Origin-Opener-Policy header.

Mobile: Super Debugger and Preview mode

On mobile, Preview mode shows a QR code and a preview URL. Scan the code with a device that has your app installed, or open the URL on that device. After you configure the SDK and URL scheme, the app opens with a small Amplitude logo at the bottom of the screen. Tap the logo to open the Super Debugger.

The Super Debugger Details tab reports Limits, Trigger (including screen conditions and pin targets), and Throttle. Toggle Ignore limits to bypass throttles during the preview. The Setup tab reports SDK version, installation type, user ID, and whether events flow into and out of the Guides and Surveys SDK. Go to Super Debugger for the full panel. The Android, React Native, and Flutter SDKs include the same debugger.

If Preview mode never reaches your app:

• iOS shows No usable data found: the device has no app that handles the preview URL. The app isn't installed on that iOS device, or the installed build doesn't register the project's mobile URL scheme. Install a build that includes the Guides and Surveys SDK and the URL scheme, then scan the QR code with that device's camera.
• Android's action sheet lists no app: the same cause. The OS has no app that handles the preview URL, so nothing appears on the share or open-with sheet. Install a build that includes the SDK and the intent filter for the URL scheme. Go to Android preview setup.
• The preview opens in a browser instead of the app: you didn't register the URL scheme, or the app doesn't call handleUrl (iOS) or handleLinkIntent (Android) when it receives the link.

Preview mode confirms rendering and conditions, not real-world delivery. To test delivery with real users, use the Testing status.

Troubleshooting checklist

Use these questions as a checklist. If you can answer "yes" to a question, that setting is unlikely to be the cause of your issue.

Is the SDK installed and booted on the page or in the app?

On web, open your browser console and enter window.engagement. A response of undefined means the Guides and Surveys SDK isn't installed on that page. Then enter window.engagement._debugStatus() and confirm the user object exists, apiKey is set, stateInitialized and decideSuccessful are both true, and num_guides_surveys is greater than zero.

Common web installation problems include an SDK that loads on some pages but not others, a boot call that runs conditionally for certain environments or user types, a boot call that runs more than once, and a Guides and Surveys SDK that loads before the Amplitude Browser SDK. If you install through Google Tag Manager with a custom HTML tag, enable Support document.write in the tag's advanced settings. Go to Troubleshoot your installation for the full list.

On mobile, use the Super Debugger Setup tab instead of the browser console. Confirm an SDK version appears, the user ID matches the user you expect, and events flow into the Guides and Surveys SDK. If Preview mode never shows the Amplitude logo, the SDK isn't handling the preview URL. Confirm you added the project's URL scheme and that the app forwards the inbound link to the SDK.

Does the API key match the project that holds the experience?

The SDK fetches guides and surveys for the project tied to its API key. If you initialize the SDK with a key from a different project, no experience loads even though the setup looks correct. Use the same API key for the core Amplitude SDK and the Guides and Surveys SDK, and confirm the key belongs to the project where you published the experience.

Is the status Published, and is the schedule active?

A Draft experience never appears to users, and a Testing experience appears only to the device IDs, user IDs, and cohorts in the Test users section. For a Scheduled experience, confirm the current time falls between the start and end dates, and remember that those times use the project's timezone. Also check whether a bulk unpublish took the experience offline.

Does the user match your targeting?

Open the targeting segments and confirm the affected user matches at least one of them. Amplitude ORs multiple segments, so a user needs to match only one, but every filter within a segment must match.

Watch for these targeting causes:

• A rollout percentage below 100% excludes users outside the bucket. The bucketing unit decides whether that assignment stays consistent across a user's devices.
• Array user properties don't flatten at evaluation time, so dotted paths like subscription.plan don't resolve. Target a flat scalar property instead.
• Cohort membership syncs on a schedule, so a user who just qualified doesn't match yet. Go to Cohort targeting for the sync rules.
• The user property the filter reads might not exist on the user's profile at evaluation time.
• Project-wide default user exclusions apply in addition to an experience's own targeting. A user who matches a project-wide exclusion segment never sees any guide or survey in the project, even if they match the experience's targeting.
• Group cohort targeting requires your instrumentation to call setGroup for each user. Attaching group properties to events creates event-level grouping, which supports analysis but doesn't qualify users for group cohort targeting. Go to Group cohort targeting uses event-level groups for details.

Does the trigger fire for this user?

Confirm the trigger matches what the user actually does:

• The None trigger never fires on its own. It waits for the SDK, a call to action in another guide, or another external trigger.
• On event tracked needs a client-side event the SDK can observe. Server-side events, Labeled Events, and Custom events don't work as triggers. On web, check the extension's Forwarded Events list to confirm the SDK sees the event. On mobile, check Event Flow on the Super Debugger Setup tab.
• When element appears fires once for each page or screen load, and it doesn't re-trigger when the element scrolls out of view and back in.
• When element clicked/tapped and element-based conditions depend on a selector that still matches. On web, that's a CSS selector or XPath against your current markup. A redesign that changes class names breaks the selector. On mobile, that's the unique identifier on the target view (accessibilityIdentifier on iOS; tag, contentDescription, or resourceName on Android; the tag passed to .amplitudeView or AmplitudeView in Jetpack Compose). If two views share an identifier, or the identifier is missing, the trigger doesn't fire.
• A trigger delay cancels the display if the user navigates away before the delay elapses, and Amplitude re-evaluates conditional logic after the delay rather than at trigger time.
• If the experience uses session properties, every configured session property condition must match at display time.

Does the current page or screen match the Where conditions?

Review the Where settings and test the match type against what the SDK actually reports.

On web, compare the rule to the exact URL, including query parameters and trailing slashes. A regex or pattern that works on your staging URL can miss in production.

On mobile, Where conditions match screen names, not web URLs. In the Super Debugger Details tab, the Screen field shows the name the SDK reports. If that string doesn't match your include rule, the experience doesn't display. Check project-wide default page exclusions under Project Settings > Guides and Surveys too. An exclusion set once at the project level applies to every experience, including ones you create later. Page and screen targeting also apply to share links: a link overrides audience targeting but not Where targeting.

Has the user already seen it?

Amplitude enables Stop showing when completed and Stop showing when dismissed by default, so a user who finished or closed the experience once doesn't get it again. A cooldown blocks the display until it expires, and a user who snoozed the experience doesn't see it again until the snooze duration passes. To make a user eligible again, open their user profile, go to the Guides or Surveys tab, and select Clear history for that experience.

Does a throttle block the display?

Throttling caps how many guides or surveys each user sees in a day, week, month, or session, and the settings for guides and surveys are separate. Check all four layers:

• The global limit and period.
• The Time Between delay, which blocks a second guide for a set duration after the user sees one.
• Advanced tag-based throttles, where the most restrictive limit wins.
• Mutual exclusivity groups, where a user who saw one item from the group doesn't see the others.

Is another experience already on screen?

Amplitude displays only one pin, popover, or modal at a time, and only one banner and one checklist. When one of those form factors already shows and another triggers, the second doesn't display, and it doesn't queue for later. If several experiences are eligible at once, priority and the tiebreaker rules decide which one wins.

Does the anchor element exist when the step renders?

Pins, tooltips, and card embeds attach to an element. If that element isn't in the DOM (web) or the view hierarchy (mobile) at render time, the step doesn't display, and Guides and Surveys doesn't skip it or fall back to another position. On web, elements that render late, sit behind a lazy-loaded component, or live inside a shadow DOM are the usual causes. On mobile, confirm each target view carries its unique identifier and that no two card embeds on the same screen share one. Pins also can't target iOS tab bar items or views inside animated containers.

Is the environment blocking the SDK?

On web, a strict Content Security Policy blocks the requests and inline styles the SDK needs. Allow https://*.amplitude.com for the script-src, connect-src, img-src, media-src, and style-src directives, and pass a nonce at initialization if your policy blocks inline styles. Guides and Surveys also has limited iframe support: selectors can't cross an iframe boundary, so each iframe needs its own SDK instance to display anything.

On mobile, the SDK requires a network connection to fetch guides and surveys. If the device is offline when the app launches, nothing displays for that session. Retry on a network, then confirm events flow in the Super Debugger Setup tab.

Does the user's SDK version support the feature?

Mobile SDKs can't auto-update, so a device on an older version doesn't receive experiences that rely on newer capabilities. The After N events in session trigger, for example, requires iOS, Android, and React Native SDK v3.7.0 or later, and guides using it don't reach users on older versions at all. Go to the mobile SDK changelog to check version requirements.

Situations that look like a failure to deliver

Some expected behaviors can feel like the experience is broken.

It works in Preview mode but not in production

Preview mode and the Testing status both relax the rules that apply to real users. Amplitude ignores limits for test users, and Preview mode lets you bypass throttles and manually fire trigger events. An experience that displays under those conditions can still fail a limit, throttle, or targeting check in production. On web, use the Chrome extension on the production page to find which condition blocks it. On mobile, add the user to Test users and set the experience to Testing so you can reproduce with live delivery rules. Use Preview and the Super Debugger Details tab when you need to inspect trigger, limit, and throttle conditions.

Only some users see it

A rollout percentage below 100% is the most common reason. With Device ID bucketing, the same user can qualify on one device and not on another, because each device receives an independent assignment. Switch to User ID bucketing when you need a consistent experience for a signed-in user across devices, or to Account ID when everyone in an organization needs the same result.

The user reports it missing after they dismissed it

An active guide follows the user across pages or screens until they complete or dismiss it. After they dismiss it, the default limits keep it from returning, so a user who dismissed the experience by accident sees nothing on later visits. Clear the experience from their history to make them eligible again.

A mobile device stays in Test User mode

Devices left in Test User mode don't render guides and surveys the way regular users do. If a mobile tester reports inconsistent behavior, confirm the mode is off, then retest.

Preview mode never opens the mobile app

Preview on mobile depends on a custom URL scheme, not on a new browser tab. If iOS shows No usable data found, or Android's action sheet lists no app, the OS has no app registered for the preview URL. Install the app on the device you scan from, confirm the URL scheme matches Settings > Projects > General > URL scheme (mobile), and scan again. This isn't a targeting or trigger failure. The OS never handed the link to your app, so the SDK never ran.

The experience is temporarily hidden

Conditional logic can hide an active guide while its temporarily hide if conditions apply. The guide stays active and becomes eligible for display again after those conditions stop matching. Check the conditions on each step when a guide disappears part way through a flow.

Group cohort targeting uses event-level groups

When instrumentation attaches group properties to individual events, Amplitude creates an event-level grouping. Event-level groups work correctly for analysis: charts show accurate data, and users appear in the group profile's users tab. However, event-level groups don't make users eligible for group cohort targeting in guides, surveys, or experiments.

For group cohort targeting to work, instrumentation must call setGroup in the analytics SDK for each user. That call sets the group on the user's profile, and targeting evaluates profile-level group membership, not event-level group properties.

If charts and group profile data look correct but targeted users still don't receive the guide, confirm that your SDK implementation calls setGroup. Go to User groups for implementation details.