Embed 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 Embed 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 Embed can appear. See Test and debug your installation for next steps.

Check user eligibility

There are two ways to check whether a user qualifies for an Embed.

From the Embed's settings page:

1. Open the Embed's settings page in Studio.
2. In the Audience targeting section, click Check eligibility.
3. Enter the user ID you want to verify and click validate. The tool reports whether the user matches your audience conditions.

From the Users page:

1. Open the Users page in Studio and search for the affected user. See Finding a User if you need help locating them.
2. Open the Eligibility tab. This shows all live experiences and whether the user currently qualifies for each one.
3. If the Embed shows as Ineligible, click it to see the reason:

• A red X next to Audiences means the user doesn't match the audience targeting rules. Click View details to see which conditions fail.

• A red X next to Frequency means the user has already seen the Embed.

Check page targeting

1. Use the Test Page Targeting tool on your Embed's settings page.
2. Open your Embed's settings page in Studio.
3. Enter the URL where you expect the Embed to appear.
4. The tool reports whether the URL matches your page and domain conditions.
5. If the result says "won't show", review your URL conditions. Common mistakes are covered in the Page targeting isn't matching section below.
6. Also confirm the domain where you're testing is selected in your Embed's page targeting settings. If you're testing in staging but only have your production domain selected, the Embed won't appear.

Embed isn't attaching to the target element

The Embed is published and the user qualifies, but it doesn't render at the expected location on the page.

CSS selector doesn't match

Embeds are placed inline using a CSS selector to identify where on the page the content should appear. If the selector doesn't match an element on the page, the Embed won't render.

Common causes:

• Your development team updated the UI and the element's class, ID, or structure changed.
• The selector targets a dynamically generated class or ID that changes on each page load.
• The element only exists for certain user roles or account types — users without access to that element won't see the Embed.

To fix:

1. Open the Embed in the Builder.
2. Check the current CSS selector in the element settings.
3. If the selector is invalid, re-select the target element, or manually update the selector field.
4. Confirm the selector shows "Unique and valid" in the Builder.

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

Element loads after the page renders

If the target element loads after the initial page render, the Appcues SDK may evaluate the selector before the element exists.

• Work with your development team to confirm the element is present in the DOM before the Appcues SDK initializes.
• If the element consistently loads late, consider targeting a parent element that is always present, or ask your development team to add a stable data-appcues attribute. See Preparing your frontend for Appcues.

Selector matches multiple elements

If the CSS selector matches more than one element on the page, Appcues can't determine which one you intended and the Embed may render in an unexpected location or not render at all.

Open the Embed in the Builder and check for an "Element not unique" warning. If it appears, narrow the selector using a more specific attribute (like an id or data-appcues attribute) or use the By order or By text filters. For detailed guidance on building stable selectors, see Troubleshoot element targeting.

Embed renders but looks wrong

The Embed appears on the page but the layout, spacing, or content doesn't look as expected.

Page CSS conflicts with Embed content

Your application's CSS may override the Embed's styling. Common symptoms include unexpected fonts, broken spacing, or elements appearing at the wrong size.

• Open your browser's developer tools (right-click > Inspect) and check whether your app's styles are being applied to the Embed's content.
• Look for CSS rules with high specificity or !important declarations that may be overriding the Embed's styles.
• If your app uses a CSS reset or global styles that affect all elements, these may interfere with Embed content. Work with your development team to scope those rules so they don't apply to Appcues elements.

Container element constrains the Embed

If the target element or its parent has restrictive CSS properties like overflow: hidden, a fixed max-height, or display: none, the Embed's content may be clipped, truncated, or invisible.

• Inspect the parent container in your browser's developer tools and check for overflow: hidden, overflow: clip, or max-height values that could constrain the Embed.
• If the container clips the content, consider targeting a different element with more available space, or work with your development team to adjust the container's CSS.

Embed content shifts page layout

Because Embeds render inline, they add content to the page's normal document flow. This can push surrounding elements down or to the side.

• This is expected behavior — Embeds are designed to integrate into your page layout, not overlay on top of it.
• If the layout shift is disruptive, adjust the target element to a location where added content won't affect critical UI elements.
• Consider using a dedicated container element (an empty div your development team adds specifically for Embeds) so the space is reserved and no shift occurs.

Multiple Embeds targeting the same element

If more than one published Embed targets the same CSS selector on the same page, only one will render. Review the audience and page targeting of each published Embed to confirm they aren't unintentionally overlapping.

To fix, either narrow each Embed's audience targeting so different user segments see different Embeds, or change the CSS selector so each Embed targets a distinct element.

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 Embed to appear on pages containing "dashboard", "settings", or "onboarding." If you use All (AND), the Embed only appears on a URL that contains all three words simultaneously (e.g., https://yourapp.com/dashboard/settings/onboarding) — which may not exist.

Switch to Any (OR) so the Embed 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.

Open your browser's console (right-click > Inspect > Console tab) and look for errors that mention a Content Security Policy related to Appcues.

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 Embed name.
• The affected user's User ID.
• The page URL where the issue occurs.
• The CSS selector the Embed is targeting (visible in the Builder's element settings).
• A screenshot or screen recording showing the problem.
• If the Embed renders incorrectly: a screenshot of your browser's developer tools showing the relevant CSS or DOM structure.
• Any console errors visible in the browser's developer tools.