Troubleshoot a tour

All controller commands return promises. Handle failures where the application can recover, and subscribe to tour:error for reporting:

const tour = useNuxtTour('onboarding')

tour.on('tour:error', ({ error }) => {
  reportError(error)
})

try {
  await tour.start()
}
catch (error) {
  // Show application-specific recovery UI when useful.
}

Event listener failures are isolated from the runtime. A broken analytics listener cannot cancel navigation.

Common error codes

• HOST_NOT_FOUND: mount one <TourHost /> before starting.
• ROUTER_NOT_CONFIGURED: pass a router in plain Vue or remove the route.
• TARGET_NOT_FOUND: confirm the semantic ID and target timeout.
• TARGET_AMBIGUOUS: remove duplicate visible matches.
• STEP_UNAVAILABLE: an exact goTo() or start({ at }) failed its when().
• TOUR_BUSY: wait for the current command instead of starting another one.

If an active target disappears, the runtime keeps the shaded presentation and waits for the same semantic target to return. The step's timeout and missing policy decide whether it skips or fails.

Progress and conditions

index and total describe definition order. total includes conditional steps because evaluating every asynchronous condition early would cause side effects and stale results. A displayed “Step 2 of 5” can therefore be the last eligible step.

Persistence

Keep completion in the application, not the tour runtime. Store a versioned flag after tour:end reports completed, and decide when to call start(). This keeps product state in one source of truth and avoids a second persistence system inside the library.