Troubleshooting

Symptoms, what causes them, and what to change. Grouped by where the problem actually lives, not by what it looks like from the outside.

Start by watching the events

Almost every silent failure announces itself through onEvent. Wire this up before guessing:

target:timeout is the one that matters most. It fires whenever a gate did not resolve in time, and it is always followed by whatever onGateTimeout did next.

On web, the overlay also states what it is doing in the DOM:

If root is absent entirely, no tour is running.

Nothing happens when I call start()

The id does not match a registered tour. start(id) looks the id up in tours and returns silently when it finds nothing. Check the string against config.id, not the file name.

The provider is not an ancestor. A hook outside the provider throws tourkit: this hook must be used inside <TourProvider>. rather than failing quietly, so if you are not seeing that error, the provider is there.

The tour started and every step was skipped. A tour whose steps all fail their gates completes in milliseconds. The event log shows tour:start, then target:timeout and step:skip per step, then tour:complete.

A step is skipped and I see target:timeout

The target never resolved within gateTimeoutMs, which defaults to 5000.

On web, target is tried in three ways, in this order:

1. An id registered through useTourTarget("post-ride")
2. A data-tour-id="post-ride" attribute
3. The string as a CSS selector

Work through the causes in order of how often they are the answer:

A gate that is about your data rather than the DOM should say so:

An invalid CSS selector resolves to null rather than throwing, so a malformed target looks exactly like a missing element.

I see a warning about a fingerprint

The tour is working. The selector is not. Healing is a safety net, and a healed step is a step whose target is already wrong. Give the element a data-tour-id and point the step at that. Details in When a target breaks.

If a step has a fingerprint and is still skipped, the fingerprint refused to guess. It only matches when the best candidate scores at least 4 and strictly beats the runner-up, so two buttons that both say "Save" resolve to nothing on purpose.

The tour only ever shows once

Completion is persisted under tour:{id}:v{version}. A completed tour starts again from step one, but a first-run trigger that checks the record will not fire.

Use the provider's own adapter, not a fresh one, or you will clear a key nobody reads:

The tour resumes onto the wrong step

You changed the steps without bumping version. The saved position is a step id, and an id that still exists in a reordered tour resumes at the new position of that id.

Bump version whenever the steps change. A saved position from an older version is discarded rather than resumed.

The tour restarts from the beginning every time

On React Native, nothing is persisted until you pass a storage adapter. There is no localStorage to fall back to.

On web, check that the provider is not remounting. The engine is created once with lazy useState, so a provider that unmounts loses everything in flight. A provider inside a route-level component, or one whose key changes on login, remounts. Put it in the root layout.

The overlay renders behind a modal

Raise theme.zIndex. It defaults to 10000, which clears most stacking contexts, but a modal library that sets a higher value wins.

The reverse is also a setting: lower it to put the tour under a fixed header.

A z-index cannot escape a parent stacking context. If your modal creates one and the tour is portalled inside it, pass container to portal the overlay somewhere else:

The card sits in the wrong place

placement is a preference, not a guarantee. Floating UI flips and shifts the card to keep it on screen, and placement.side in the card props reports where it actually landed.

On React Native, placement: "left" and "right" fall back to auto, because a 320px card does not fit beside anything on a 390px screen.

A step with target: null centres the card and cuts no hole. That is the intended shape for a final step, not a bug.

Escape does not close the tour

dismissible: false on the step or the tour. Escape is ignored, and a custom card is told to hide its skip control. It defaults to true.

Clicking the highlighted element does nothing

That is interaction: "block", the default. A full-screen shield absorbs every press, including inside the hole, so the highlight is purely visual.

advance-on-press does not press the underlying element. That is deliberate and identical on both platforms. See Interaction.

The scroll does not happen

scrollIntoViewIfNeeded is a no-op when the element is already fully inside the viewport, so a target that is only slightly clipped by a sticky header will not scroll. Give it an explicit block:

On React Native, scrolling needs the container's ref:

Use useRef<ComponentRef<typeof ScrollView> | null>(null). useRef<ScrollView> does not typecheck in current React Native types, because the imported name is the component rather than the instance.

React Native: the hole is offset from the element

TourTarget wraps a component that forwards neither onLayout nor a ref, so the spotlight falls back to the wrapper, whose box includes the child's margins. Development logs this by name.

Forward onLayout to that component's root view:

React Native: the padding is doubled

TourTarget renders a wrapping View, and its style prop goes on that wrapper. Give it layout only: flex, alignSelf, margin. Padding on the wrapper is added to the padding the child already applies.

React Native: a strip along the bottom stays lit

A custom Backdrop that sizes itself from useWindowDimensions(). Under Android edge-to-edge the window it reports is shorter than the screen by the system bars.

The Backdrop slot receives size, the measured box the overlay actually covers. Use that.

React Native: two elements fight over one id

Two TourTargets with the same id are mounted at once. Usually a target inside a list that was not given a per-row id.

The blur does nothing on React Native

blur.enabled alone is not enough. Install @react-native-masked-view/masked-view and expo-blur, rebuild, then hand the modules to createBlurBackdrop and pass it as the Backdrop slot. Without that, the dim scrim stays and development logs one warning naming what to install.

The package does not import those modules itself on purpose. The reasoning is in Customization.

A theme token does nothing

Four tokens are not what they look like:

All of them are in the Theme reference.

A hint ignores my provider theme

TourHint merges the defaults with its own theme prop and nothing else. The provider theme and the tour theme do not reach it.

A dismissed hint will not come back

Dismissal writes dismissed to tourkit:hint:{id} and the hint never renders again on that device.

A hint whose target does not resolve renders nothing at all: no dot, no error, no warning. It appears as soon as the element mounts.

The recorder panel never appears

The panel polls GET /status and renders only while tourkit record is answering. Check, in order:

1. tourkit record is running in a second terminal.
2. <TourRecorder /> is mounted, inside the provider, in a development build.
3. Nothing is blocking http://127.0.0.1:5178.

Pass autoShow={false} to render it unconditionally, which is the clipboard flow with no server.

npx tourkit only works when npm wrote the shim it looks for. Bun on Windows writes tourkit.exe and tourkit.bunx instead, and npx then tries to fetch a package called tourkit from the registry and fails with a 404. Use the runner that matches your install.

The native recorder captures nothing

It can only capture taps on mounted TourTargets. A production build has no queryable view tree to resolve anything else against, so you wrap first and record second. The web recorder has no such limit and needs nothing prepared.

Asking a question returns 422

The model named a target that is not in the manifest. status becomes failed with reason: "unknown-target", and nothing renders. This is the check working: a partial tour pointing confidently at empty space is worse than no tour.

The usual cause is a thin manifest. A target id of btn-4 with no label tells the model nothing.

Other reasons: malformed covers a network error, a non-2xx response and unparseable JSON. empty means the model returned no usable steps.

Everything re-renders more than it should

tours built inline. The provider pushes tours into the engine from an effect keyed on its identity. A fresh array on every parent render re-runs that effect and re-renders the overlay. Hoist it to module scope, or memoize it.

The same applies to theme, storage, nav and onEvent. All five can change mid-tour without restarting anything, which is what makes a dark mode toggle safe, and which is also why a new object every render is not free.

useTourSnapshot where useTour would do. The snapshot is a new object on every engine change. useTour() selects a boolean, so it re-renders only when the tour starts or ends.

An inline selector. useTourSelector reads through the callback you pass, so an inline arrow re-subscribes on every render. Define it outside the component or wrap it in useCallback.

TypeScript rejects my when or gate

Without the annotation, TypeScript infers the context from the object literal and widens "free" to string, so a predicate typed against AppContext no longer matches. The full explanation is in the Provider reference.

Still stuck

Steps that never resolve, tours that never start, and cards in the wrong place are all visible in the snapshot. Log the whole thing:

status is idle, resolving or active. A step stuck on resolving is waiting for a gate. rects is empty for a target that was never measured.