Why product tours break when your app changes, and how to stop it

A product tour breaks when it can't find the button it's supposed to point at. Your team ships a redesign, renames a menu, or a list loads a second late, and the tour points at nothing or quits halfway. It's one of the most common complaints in G2 reviews of tour tools, and it's the reason a lot of teams stop building tours after the first few.

Key takeaways

• A tour breaks because it remembers each button one way, and that one way stops working when your app changes.
• Redesigns, slow-loading content and apps that swap screens without reloading cause most broken tours.
• Tours last longer when each step is saved several ways, waits for slow content, and reports when it fails.
• Clickalong records tours like that, and its AI can still point at the right button when a recorded step can't find it.

What actually breaks a product tour?

A tour breaks when the element a step points at has moved, been renamed or isn't on the screen yet. Most tour tools save each step as a CSS selector, which is a line of code that tells the browser which element to highlight. When your developers change the page, that line can stop matching, and the step has nothing to show.

These are the usual causes:

1. A redesign or a renamed button. The button still exists, but its code changed, so the saved selector no longer finds it.
2. Content that loads late. Dashboards, tables and search results often appear after the page itself. A tour that looks once and gives up finds an empty spot.
3. Apps that change screens without reloading. Most React, Vue and Angular apps swap content in place. A tour that only checks when the page loads misses the new screen.
4. Lists the app builds on the fly. Dropdown items and table rows that come from your data change from user to user, so a step pinned to one of them is fragile.
5. Something covering the button. A cookie banner, a modal or a chat window can sit on top of the control the tour wants to highlight.

What reviewers say about broken tours

The pattern shows up across tools. In WalkMe's 1 and 2 star reviews on G2, teams describe builds that don't work as expected and put launch dates at risk. An Appcues reviewer on G2 says it couldn't handle dropdown items that the app fills in with JavaScript, and the team gave up on it. Other reviews mention needing a developer or CSS to fix a guide after a release.

None of this means tours are a bad idea. It means a tour has to expect your app to change.

How do you build product tours that don't break?

Build each step so it has a backup plan. These five habits cover most of it:

1. Give key buttons a stable ID. Ask your developers to add a data-testid attribute to the buttons your tours use. It stays the same when the design changes.
2. Save more than one way to find each step. Keep the button's text and its role (button, link, tab) as backups to the CSS selector.
3. Wait for slow content. A step should keep looking for its button for a while instead of failing on the first check.
4. Track which steps fail. Measure how often each step can't find its target and fix the worst ones first.
5. Keep tours short. A five-step tour has fewer things to break than a fifteen-step one, and users finish it more often.

How Clickalong keeps tours working

Clickalong is built around tours that survive releases. You record a tour by clicking through the task once in Chrome with the Clickalong recorder, and it does the backup work for you.

• Every step is saved up to six ways. Clickalong keeps a main selector plus up to five backups, including the button's role, its name and its exact text. It uses a data-testid when your app has one, but it doesn't need it.
• It never points at the wrong button. A step only highlights when exactly one element on the page matches. If two buttons match, it doesn't guess.
• It waits for slow content. When a step's button isn't on the screen yet, Clickalong checks again every second for up to two minutes and carries on the moment it appears. That's what keeps tours working in apps that change screens without reloading.
• Its AI covers the gap. If a button really is gone, Clickalong's AI looks at what's on the user's screen and points at the right control, marked "Suggested by AI", so the user isn't left stuck.
• It tells you what broke. The Tours page shows how often each step misses, and the weekly email lists tours that need a fix.

You don't always need a tour, either. With "Show me" guidance, a user asks how to do something and Clickalong points at the button on their current screen, with nothing recorded in advance. Guided tours and "Show me" guidance both start on Essentials ($95 a month), with no limit on how many tours you publish. Every new workspace gets a 14-day trial of every feature, no card.

If you're comparing tour tools, see product tour software compared and what an AI support agent does.