Common install failures
Wizard and SDK failure matrix with exact fixes — from shipped wizard/SDK behavior.
Work through the row that matches your symptom. For “install looked fine but the app is empty,” use No data after the install itself succeeds.
Failure matrix
| Failure | Likely cause | Fix |
|---|---|---|
| Wizard says unsupported project | Pure backend / no supported frontend framework | Install on a JS frontend package, or use HTML CDN |
| Approve never finishes | Popup blocked / browser Approve abandoned | Allow popups; complete dashboard Approve; retry CLI |
Old command npx humanbehavior-js | Wrong package | Use npx @humanbehavior/wizard@latest |
| Hydration mismatch after provider wrap | Provider around entire App Router tree | Use a leaf client HumanBehaviorInit — Next.js |
needs-attention install status | Wizard finished with build/lint problems | Open humanbehavior-install-report.md in the repo; fix listed issues |
| Max turns on monorepo | Wizard turn budget exhausted walking packages | Run from the frontend package root; raise HB_WIZARD_MAX_TURNS locally only if needed |
| Env Read denied in wizard logs | Expected agent policy | Use wizard env tools / paste keys; do not expect arbitrary .env reads |
| CDN works locally but not prod | Ad blocker or CSP | Confirm Network tab; add reverse proxy; relax CSP for ingestion host |
| Data in wrong project | Wrong API key / wrong Environments key | Copy key from Settings → Environments for the project you open in the UI |
Human Behavior API Key is required | init called with empty/undefined key | Ensure env vars are available in the browser (NEXT_PUBLIC_… / VITE_…) and restart dev server |
| Double init / unexpected singleton | Second init returns existing tracker | Clear hard refresh; avoid mounting two providers with different keys on one page |
| Minified stacks only | Maps not uploaded or release mismatch | Source maps — same release/dist at runtime and upload |
| Short bounce sessions empty | Default 5s minimum duration | Set minimumDurationMilliseconds: 0 for landing pages that exit immediately |
Wizard device flow
| Step | What happens |
|---|---|
| 1 | CLI creates a pending wizard_sessions row + user code |
| 2 | Browser Approve binds project + API key |
| 3 | CLI polls until approved / error / expired |
| 4 | Wizard writes env vars and framework init code |
If the session expires, restart the wizard — do not reuse a stale user code. Install status fields (installStatus, installReport, etc.) power the dashboard “needs attention” state and the generated humanbehavior-install-report.md.
Framework-specific gotchas
| Framework | Common miss |
|---|---|
| Next.js App Router | Init in a Server Component or root layout without "use client" |
| Remix / Vite SPA | Key only in server env — not exposed to the client bundle |
| HTML CDN | Script order — init before interacting; wrong global name |
After install succeeds
- Verify — confirm
init+eventsin Network - Interact for >5s (or set
minimumDurationMilliseconds: 0) - If still empty → No data