If you're on the page where an Experience should appear but nothing shows up, there are two likely causes: the URL rule isn't matching the current page, or the element the Step is anchored to isn't found. This article covers how to diagnose and fix both.

Check the output for two messages:

Each Step in a Chameleon Experience can have a URL rule that controls which page it appears on. This is something you can set up when creating your Experience.

If the rule does not match the current page, the Step will not display — even if the snippet is installed, the user is identified, and the audience matches. URL mismatches are one of the most common causes of Experiences not showing.

URL rules are evaluated against the full URL of the current page, including the path, query parameters, and hash fragment. Chameleon supports four rule types:

Run the Debugger with your Experience ID in the browser console:

The output will let you know if the URL rules do not apply to the current page.

You can also check on the Builder. Open the Tour in the Builder for the URL you want to check, and look at the top-right corner. A message will appear if the URL rule for the step you're viewing doesn't match the URL:

If your page URL contains query parameters like ?onboarding=true, an Exact rule that does not include the full query string will fail. Switch to Contains if the parameter changes.

A URL like /settings#billing will not match a rule for /settings when using Exact match. Use Contains or add an explicit rule that includes the hash.

A rule for app.example.com/dashboard will not match staging.example.com/dashboard. Each subdomain must be covered by its own rule, or use a Contains rule for the path only.

URLs that include variable IDs (e.g. /projects/12345/overview) will not match a static rule like /projects/overview. Use a Contains rule for a stable part of the path (/projects/) or a Regex rule to match the pattern.

URL rules can be set per Step. If Step 1 matches but Step 2 has a stricter rule, the Experience will start but then stall. Check each Step's URL rule individually in the Builder.

In SPAs, the URL changes via the browser's History API without a full page reload. Chameleon polls for URL changes regularly and will re-evaluate URL rules when the URL updates. However:

👉 Read How to troubleshoot display issues on single-page applications for more detail.

When a Chameleon Step is configured to attach to a specific element on the page — either as a trigger, as an anchor or as an Element Rule — that element must be present and accessible when the Experience tries to display. If it is not found, the Step waits indefinitely and nothing shows. This article covers how to diagnose and fix element-related display issues.

Chameleon uses page elements in two ways:

Both types use CSS selectors to identify elements.

Run the Debugger in your browser console:

If the output mentions "element not found" or the Step appears to be waiting with no error about URL or audience, the element is likely the cause.

You can also inspect the page manually: right-click where the element should be and select Inspect. If it is not in the DOM, Chameleon will not find it.

Some elements load after the initial page render; inside a modal, after an API call completes, or via lazy loading. If Chameleon checks for the element before it exists in the DOM, the Step waits.

Fix: If the element eventually appears, Chameleon will detect it and display the Step once it does. If the element never appears on initial load, consider removing the element requirement or using a URL rule to restrict the Step to the page where the element always exists.

When the Builder records a CSS selector, it captures the exact path to the element at that moment. If your application generates dynamic class names, IDs, or deeply nested structures that change between sessions, the stored selector may no longer match.

Fix: Open the Step in the Builder, click the element selector, and use the selector editor to simplify or broaden it. Prefer stable attributes like a data-testid, a unique class, or a readable element ID over auto-generated values.

An element with display: none is present in the DOM but not visible. Depending on the Experience type, Chameleon may not treat this as a valid anchor.

Fix: Check the element's computed styles in browser DevTools. If the element has display: none adjust your URL rule or display conditions so the Step only attempts to show when the element is visible.

If the Experience is showing but appearing behind other page elements — menus, modals, fixed headers — the issue is CSS stacking context, not element detection. Chameleon Experiences have a default z-index, but your application's CSS may render certain elements on top of them.

Fix: Read Using CSS layering to adjust where your Experience shows up for how to use custom CSS to adjust the z-index of Chameleon Experiences.