Troubleshooting
| Symptom | Check |
|---|---|
| Guides never appear in my app | 1) Settings → Environments shows "SDK connected" for the env in your key. 2) The guide is published to that environment and not paused. 3) Targeting/URL rules match (use guidely.getState() in the console → eligible). 4) Frequency: once guides only show once per user; use guidely.reset() or startGuide(key) while testing. |
401 Unknown public key | The key was rotated or belongs to another environment. Copy it again from Settings → Environments. |
403 Origin … is not allowed | Add your app origin (scheme + host + port) to the environment's allowed origins, or clear the list for development. |
| Tooltip attaches to the wrong element / nothing | The selector resolves to 0 or >1 elements. Use the picker, prefer data-tour / id, and test with guidely.highlight(selectors). Increase waitMs for lazily rendered elements. |
| Element picker never connects | Pop-ups blocked (allow for the dashboard origin); SDK not installed on that page; apiUrl of the SDK does not point at this dashboard; token expired (2 h). |
| Events missing in the dashboard | Analytics disabled in Privacy settings; consent: "pending" without grantConsent(); ad blockers (self-host guidely.js and the API under your domain); check the Events page with the right environment. |
| No replays in Replays | Session replay is enabled in Settings → Privacy & data and the sample rate is above 0 (or call guidely.startSessionRecording()); analytics and consent are granted; the SDK option sessionReplay isn't false; for script-tag installs guidely-recorder.js is served next to guidely.js; a strict CSP allows that script and connect-src to the API. Recordings appear a few seconds after activity. |
| Page analytics empty | "Collect page URLs" is on (paths are not stored otherwise) and autocapture page views are on. |
| Errors show minified names | Upload source maps for that build (Settings → Source maps). Check that the map's path matches the URL the minified file is served from (--url-prefix), and if the SDK sends a release, that the maps were uploaded with the same --release. Maps apply to occurrences already recorded, but grouping only changes for new ones. |
| Source map upload returns 401 | The key was revoked, is a public pk_ key, or lacks sourcemaps:write. Create a new key in Settings → Source maps; npx @guidelytech/sourcemaps verify checks it. |
Invalid environment configuration at boot | A required env var is missing (DATABASE_URL, SESSION_SECRET ≥32 chars). |
prisma migrate fails in CI | Use pnpm db:deploy (no interactive prompt) with a reachable DATABASE_URL. |
SDK bundle not found at /sdk/guidely.js | Run pnpm --filter @guidelytech/embed build (copies the IIFE bundle into apps/web/public/sdk). |
| Styles of the guide look wrong in my app | Guides render in a Shadow DOM; host CSS does not apply. Use Branding (Settings) or per-guide Appearance. |
| Duplicate guides after navigation | Make sure only one GuidelyProvider / createGuidely exists; React Strict Mode double-mount is handled, but two providers are not. |
Debugging helpers: localStorage.setItem("guidely:debug", "1") (verbose console logs), window.__guidely (the active client in the demo apps), GET /api/health.