Common symptoms
The guide does not appear
The guide does not appear
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 guide loads but does not answer
The guide loads but does not answer
The launcher renders but chat returns nothing.
- Confirm the
/bootrequest succeeds. Ordinary app-ID/origin boot returns200, or one of400(invalid request),403(for exampleboot/origin_not_allowed), or429(rate limit, with aRetry-Afterheader). A403usually means the app, hostname, visitor reference, or request origin did not pass validation. If the200response setsfeatures.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 replayedcustomer_identity_tokenreturns401; 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_allowedis expected: production authorizes HTTPS origins only and has no loopback special case, sohttp://localhost:3000matches nothing. See local development for how to run a dev server against a verified domain. - Confirm
/chatis authorized. Each request needs a validAuthorization: Bearer <visitor-jwt>. That token is minted at/bootand has roughly a 15-minute TTL, so a missing, invalid, or expired token returns401(chat/unauthorized, orjwt_expiredonce it ages out). The fix is almost always an upstream/bootfailure. /chatalso enforces visitor and workspace rate limits, returning429with aRetry-Afterheader when exceeded. See Rate limits.- If the killswitch (
GP_KILLSWITCH=true) is active,/bootreturns a200privacy-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.
Voice does not start
Voice does not start
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
Vkey is off by default. Setdata-voice-hotkey="true"on the snippet (or turn the switch on in the dashboard) before the key will wake voice.
A keyboard shortcut does nothing — or takes a chord you wanted
A keyboard shortcut does nothing — or takes a chord you wanted
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, atextarea, acontenteditableregion, 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,
cursorand the defaultfloating. Withdata-launcher-modeset tomanualorhidden, and in headless mode, there is no launcher to summon and the chord stays with your page. It also goes quiet afterPuntego.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.
- Leave
data-summon-hotkeyunset — off is the default, and an install that never opted in never callspreventDefaulton 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
windowduring the bubble phase and stands down wheneverevent.defaultPreventedis already true, so any handler of yours that runs first and callspreventDefault()wins that keystroke.
data-voice-hotkeyis 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
Vkey with your page. The microphone stays visible in the panel with its reason rather than disappearing.
The launcher looks different on mobile
The launcher looks different on mobile
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.