Flow isn't appearing

Work through these checks in order. Most issues are caught in the first three steps.

Check that Appcues is installed

Open the Appcues debugger on the page where you expect the Flow to show. Confirm all rows display green checkmarks.

If any rows show red errors, you have an installation issue that needs to be resolved before the Flow can appear. See Installation Testing / Debugging for next steps.

Check user eligibility

1. Click Audiences > Users and search for the affected user. See Find and inspect users.

2. Open the Eligibility tab. It lists every live experience and whether the user qualifies for it.

3. To include page and domain rules, enter the page's URL in Page URL and click Check page.

4. If the Flow shows Not eligible, click See why. Each group of rules shows Met or Not met:

   • Audience not met: the user doesn't match the audience rules.

   • Page not met: the page doesn't match the page or domain rules.

   • Frequency not met: the user already saw it, or a frequency limit is blocking it.

Eligibility doesn't check trigger rules, so an event-triggered Flow can show Eligible and still wait for its event.

Check page targeting

Use Test URL targeting on the Flow's settings.

1. Open the Flow and click Settings.
2. In Where this appears, click Test URL targeting.
3. Enter the URL where you expect the Flow to appear. The result is Will show, Will not show, or Will show when installed (the rules match, but Appcues isn't installed on that domain).

If the result is Will not show, review your URL conditions. Common mistakes are covered in the Page targeting isn't matching section below.

Also confirm the domain where you're testing is ticked under Only the domains I choose in Where this appears. If you're testing in staging but only have your production domain selected, the Flow won't appear.

Check frequency settings

If you have a strict frequency limit enabled and multiple live Flows showing, your Flow may be blocked from appearing. To override it for one Flow, tick Override account frequency limit on this Flow on the Flow's Settings tab.

If the Flow is set to Show once and the user has already seen it, it won't appear again. To test:

• Reset the user's profile to make all "Show once" Flows eligible again: in Audiences > Users, open the user, click ⋮, then Reset profile. This permanently deletes their profile data.
• Use Test mode or a permalink to bypass frequency and audience rules entirely.

If a Show once Flow keeps appearing instead, see Flow keeps appearing after users have seen it.

Step isn't showing

The Flow starts, but a specific step doesn't appear. Use the Appcues debugger to identify the cause — it shows real-time details about which step is active and any errors.

Incorrect CSS selector

While the Flow is running, the debugger shows the active step under the Showing Flow section. If a step shows the error "Content omitted", the Tooltip or Hotspot is anchored to an element that isn't unique or can't be found on the page.

To fix:

1. Open the Flow in the Builder.
2. Navigate to the affected step.
3. Click the gear icon on the step to view the current selector.
4. Use Reposition Tooltip or manually refine the selector to target a unique, valid element. Add filters like Text or Order to narrow it down.

For detailed guidance on building stable selectors, see Troubleshoot element targeting.

Incorrect navigation step

If the debugger's Showing Flow section turns grey and says "Wait for matching page", the navigation step in the Flow doesn't match the URL the user actually navigated to.

To fix:

1. Open the Flow in the Builder.
2. Find the navigation step that precedes the missing step.
3. Confirm the path in the navigation step matches the actual destination URL. For example, if users click a link to /settings but the navigation step is set to /about, the Flow breaks.
4. If the destination URL contains dynamic segments (IDs, query parameters), use wildcards. See Build a Flow across pages for how to set these up.

Page tracking lost

If the debugger shows a red error next to Tracking Pages that doesn't recover, Appcues has lost track of the current URL. Expand the Tracking Pages section in the debugger — if the "Last Tracked URL" differs from the current URL, page changes aren't being tracked. 

To fix, set the "enableURLDetection" setting to true in the window.AppcuesSettingsobject. See Single-Page Application Guide.

Flow breaks on page refresh

If the user refreshes the page or the application triggers a full page reload during a Flow, the Flow stops. This is expected — Flows don't persist across full page loads.

To prevent this:

• If a page refresh is unavoidable at a certain point, consider splitting the Flow into two separate Flows — one before the refresh and one after, triggered on the destination page.

Previous step didn't complete

If a Tooltip asks the user to click a specific element to advance (for example, a navigation link), clicking elsewhere on the page won't progress the Flow. The step requires interaction with the targeted element.

Confirm the step's advance behavior in the Builder:

• If the step advances on element click, the user must click the exact targeted element.
• If the step advances on button click, the user must click the "Next" button within the Tooltip.

Flow keeps appearing after users have seen it

A Flow set to Show once keeps coming back for the same users. On the Flow's analytics page, Total users is much higher than Unique users.

The Flow starts with a Tooltip or Hotspot group

In legacy Flows, a Flow that starts with a Tooltip or Hotspot counts as shown only after the user interacts with every step in the first step group. Interacting means clicking Next, clicking the target element, or dismissing the step. A user who sees the first Tooltip and keeps working without touching it sees the Flow again later.

To fix it, do one of the following:

• Put the first Tooltip in its own step group. The user then only has to interact with that one Tooltip for the Flow to count as shown.
• Start the Flow with a Modal or Slideout, which counts as shown as soon as it appears.
• Rebuild the Flow in Flows 2.0, where a Tooltip counts as shown when it displays, whether or not the user interacts with it.

See Set Flow Frequency for how each step type is tracked.

The Flow uses Show until completed (Flows 2.0)

Show until completed stops showing the Flow only after the user clicks the button on the last step. Users who reach the last step and leave without clicking it see the Flow again. On the Flow's analytics page, check the Completed column. If it's near zero, users are reaching the end without finishing.

Flow priority conflicts

If multiple Flows target the same page and audience, only one shows at a time. By default, the most recently published Flow takes priority. On the next qualifying page view, the next Flow in priority order shows.

If the wrong Flow is appearing:

1. Review Flow Priorities to understand the priority order.
2. Adjust priority tiers or narrow audience/page targeting so Flows don't compete.
3. Check which Flows the user is eligible for on their Eligibility tab, then compare those Flows' weights in How this competes with other experiences on each Flow's Settings tab.

Page targeting isn't matching

Regex patterns

If using a regex pattern for URL matching, confirm:

• The operator is set to matches regex (not "contains" or "is").
• The pattern is valid. Test it with a regex tester.

AND vs OR conditions

If using multiple URL conditions, check whether they use All (AND) or Any (OR) logic.

Example of a common mistake: You want the Flow to appear on pages containing "account", "dashboard", or "payments." If you use All (AND), the Flow only appears on a URL that contains all three words simultaneously (e.g., https://yourapp.com/account/dashboard/payments) — which may not exist.

Switch to Any (OR) so the Flow appears on any page containing at least one of those words.

Content Security Policy blocking Appcues

Some applications use a Content Security Policy (CSP) that blocks external resources not explicitly allowed. This can prevent the Appcues SDK or Builder from loading, as well as block styling, fonts or other resources.

To confirm:

1. Open your browser's console (right-click > Inspect > Console tab) and look for errors that mention a Content Security Policy related to Appcues.
2. If you see CSP errors, your development team needs to add Appcues domains to the allow list. See Content Security Policies for the required configuration.

Still stuck?

Collect the following and contact support:

• The Flow name 
• The affected user's User ID.
• The page URL where the issue occurs.
• A screenshot or screen recording showing the problem.
• The step number where the issue occurs (if a specific step isn't showing).
• Screenshots of the debugger output, especially the Showing Flow section and any error messages.
• Any console errors visible in the browser's developer tools.