Troubleshooting

My tour doesn't appear

The most common cause is that the SDK is not fully initialized before start() is called. Make sure init() runs with a valid apiKey and baseUrl before you call start(). Enable debug: true in your init() call and open the browser console — the SDK logs each step of its fetch-and-match process, and the output will tell you whether the fetch succeeded and whether any tour's urlPattern matched the current pathname. If the console shows a successful fetch but no match, compare the urlPattern set in the tour editor against window.location.pathname exactly — the SDK matches against the pathname only, not the full URL including query string or hash. If no published tour exists for your API key, start() silently exits; make sure the tour is published and not in draft-only state.

The Chrome Extension can't capture a selector

The extension injects a content script into the active tab to power the element picker. If the picker activates but highlighting does not follow your cursor, the page's Content Security Policy may be blocking the content script from running. The extension is an MVP shell whose content script currently matches <all_urls> for development simplicity — stricter CSP configurations on some pages may still interfere. Elements inside iframes or shadow DOM trees are also outside the picker's reach because the content script operates on the top-level document only. If the element you want to target did not exist in the DOM when you activated the picker — for example, a tooltip or modal that only appears after a user interaction — you will need to trigger that interaction first, then activate the picker while the element is visible.

Tour starts but skips a step

A step is skipped when its targetSelector cannot be resolved after retries. This usually means the selector points to an element that is off-screen, hidden with display: none or visibility: hidden, or not yet in the DOM when that step runs. Check the selector in the tour editor by pasting it into your browser's DevTools console (document.querySelector('your-selector')) on the target page to confirm it returns the right element at the right time. If your app renders content asynchronously, consider delaying the start() call until your page has fully hydrated, or adjust the step order so the targeted element is guaranteed to exist before that step is reached.

Analytics events aren't showing up

First verify the events are actually firing by enabling debug: true in init() and watching the browser console — the SDK logs each emitted event. If you are using on() to forward events to your own analytics tool, confirm the handler is registered before start() is called; handlers registered after a tour has already started will miss events that fired earlier. If events appear in the console but not in the Geyed dashboard, allow a few minutes for the dashboard to process and display new data.

My published tour isn't live

After you click Save & Publish in the tour editor the tour goes live immediately, but your users' browsers may serve a cached copy of the SDK response. The SDK fetches tours from the backend on each start() call, so a hard refresh in the browser (bypassing the service worker or HTTP cache) is the fastest way to confirm the updated tour is being served. If you recently changed the tour's urlPattern, make sure the new pattern actually matches the page you are testing on. You can also confirm the current published version by calling start() with debug: true and checking the console — the SDK logs the tours it received from the backend, including their version IDs.