Skip to main content
Most launch issues fall into one of four buckets: the guide does not mount, it mounts but does not answer, voice does not start, or the guide cannot reach a control on the page. Work through the symptom that matches, then confirm the result in your browser.

Common symptoms

The boot script runs but no launcher renders.
1

Confirm the boot script attributes

The script needs both data-app-id (your app ID, the gp_ token) and data-gp-api. Without data-gp-api the worker is unreachable: the runtime logs an error and returns an empty URL, so nothing mounts. See Install Puntego for the full snippet.
2

Check the domain allowlist

The current hostname must be on the workspace domain allowlist, and its DNS TXT verification must have succeeded. Add and verify it from Dashboard → Install → Domains. Review the steps in Authorize your domains.When /boot rejects the page origin (403 boot/origin_not_allowed), the widget renders nothing on that page, because a visitor cannot fix an install. On localhost, *.localhost and 127.0.0.1, a small badge explains why instead. In both cases an error listener receives the code boot/origin_not_allowed.Dashboard → Install shows the reason Puntego logged for each refused origin, for example Rejected: domain not verified, with the fix next to it. See diagnose an install that does not boot.
3

Pass the nonce on strict CSP sites

If your site uses strict CSP, set the nonce on both nonce and data-nonce, and allow the worker origin and microphone Permissions-Policy as described in Content Security Policy.
4

Check the route rules

data-routes is evaluated at load (and re-checked on SPA route changes). If any allow rule is present, the path must match one to mount; a leading ! deny always wins. Confirm the current path is not excluded in Configuration.
The launcher renders but chat returns nothing.
  • Confirm the /boot request succeeds. Ordinary app-ID/origin boot returns 200, or one of 400 (invalid request), 403 (for example boot/origin_not_allowed), or 429 (rate limit, with a Retry-After header). A 403 usually means the app, hostname, visitor reference, or request origin did not pass validation. If the 200 response sets features.privacy_controls_only, the assistant is intentionally unavailable: inspect/Forget remains accessible, but chat and normal runtime routes stay blocked. On a workspace eligible for full assistant boot, an explicitly supplied invalid, expired, or replayed customer_identity_token returns 401; mint a fresh one on your authenticated server. Identity-bound boot fails closed and never falls back to an anonymous assistant session.
  • If you are on a dev server, a 403 boot/origin_not_allowed is expected: production authorizes HTTPS origins only and has no loopback special case, so http://localhost:3000 matches nothing. See local development for how to run a dev server against a verified domain.
  • Confirm /chat is authorized. Each request needs a valid Authorization: Bearer <visitor-jwt>. That token is minted at /boot and has roughly a 15-minute TTL, so a missing, invalid, or expired token returns 401 (chat/unauthorized, or jwt_expired once it ages out). The fix is almost always an upstream /boot failure.
  • /chat also enforces visitor and workspace rate limits, returning 429 with a Retry-After header when exceeded. See Rate limits.
  • If the killswitch (GP_KILLSWITCH=true) is active, /boot returns a 200 privacy-controls-only session. The embed hides the assistant composer, preserves inspect/Forget access, and blocks normal runtime traffic.
  • If consent mode requires opt-in and the visitor has not accepted, the guide will not collect input or respond. Confirm the mode in Privacy and PII.
The microphone or spoken responses are unavailable.
  • Voice is optional per workspace. Confirm it is enabled for this workspace before debugging further.
  • In production, missing provider credentials make voice unavailable while text guidance remains active. The internal mock voice is available only in development and tests.
  • Strict-CSP sites need a microphone Permissions-Policy; without it the browser blocks capture. See Content Security Policy.
  • Push-to-talk on the V key is off by default. Set data-voice-hotkey="true" on the snippet (or turn the switch on in the dashboard) before the key will wake voice.
The guide ships two keyboard shortcuts, and both are off until you turn them on. Neither one is taken from your page by default.Nothing happens when I press ⌘K.
  • Set data-summon-hotkey="true" on the install snippet, or turn on Open the guide with ⌘K under Dashboard → Guides → Actions → Proactive Behavior to arm it everywhere.
  • The chord is deliberately ignored while focus is in a text field — an input, a textarea, a contenteditable region, or the guide’s own composer — because ⌘K there usually means “insert link” or “kill line” to the visitor.
  • It only arms on the launcher modes that render a guide cursor, cursor and the default floating. With data-launcher-mode set to manual or hidden, and in headless mode, there is no launcher to summon and the chord stays with your page. It also goes quiet after Puntego.hide().
  • It only ever opens. Pressing it on an already-open panel keeps the panel open and returns focus to the composer; closing is Escape, never the chord.
⌘K collides with my own command palette or search.
  • Leave data-summon-hotkey unset — off is the default, and an install that never opted in never calls preventDefault on the chord.
  • If the workspace default turned it on, set data-summon-hotkey="false" on that page’s snippet. An explicit attribute always beats the workspace default.
  • You can also keep the chord in code: the guide listens on window during the bubble phase and stands down whenever event.defaultPrevented is already true, so any handler of yours that runs first and calls preventDefault() wins that keystroke.
V does nothing, or V stopped working in my app.
  • data-voice-hotkey is off by default too; see “Voice does not start” above.
  • Even when it is on, the key is only armed while voice can actually be spent. A boot that came back without voice (a privacy-controls-only session, for example), a microphone the visitor denied, or a monthly voice allowance that ran out mid-session all disarm it and leave the bare V key with your page. The microphone stays visible in the panel with its reason rather than disappearing.
The experience changes on touch or narrow screens.The runtime detects touch-primary or narrow (under 768px) screens and switches to the bubble experience, but only when the launcher mode is cursor. With the default floating launcher, narrow and touch screens keep the floating button. If you expected the floating button and see a bubble, check whether data-launcher-mode is set to cursor in Configuration.

What the guide cannot see

The guide reads the live DOM of the surface in front of the visitor. A few surfaces fall outside that line of sight by design.

What that means for you

  • Prefer real DOM controls for the critical path you want Puntego to guide.
  • Keep payment fields, support widgets, and CAPTCHA flows outside the “point here next” promise, since they typically live in iframes.
  • Register retained closed shadow roots up front so their component internals are pointable.

Next steps

Authorize your domains

Add a hostname, verify the DNS TXT record, and clear 403 boot errors.

Content Security Policy

Allow the worker origin, set the nonce, and grant the microphone policy for voice.

Errors

Look up the exact namespace/reason envelope and status code you received.

Guide Tools SDK

Register shadow roots and targets so the guide can reach more of your page.