Troubleshooting
Start with the table for the part that's misbehaving: the widget in your app, or the CLI in CI. The gotchas checklist at the end covers the setup mistakes behind several of these symptoms.
Widget (@lyba/react)
| Symptom | Likely cause | Fix |
|---|---|---|
| Nothing appears when opening a review link | enabled is false on the preview build | Check the value your bundler inlined and use an explicit public preview env var. |
| Nothing appears for normal visitors | Expected behavior | The overlay only mounts for users with a Lyba review token. |
| Overlay appears on production | Production gate is wrong | Make enabled false for production and redeploy. |
| Toolbar says the review link is invalid or expired | Token expired, session ended, or CSP blocked validation | Try the durable /r/<slug> review link again and check connect-src. |
| Review link loses the token after preview auth | Preview protection redirected the user | Let the client access the preview without SSO, or use your host's preview bypass mechanism. |
| Pins move after a redesign | DOM anchors changed | Add stable data-testid, data-lyba-id, or id hooks to important elements. |
| Next.js import/build fails | Old package version | Use @lyba/react@0.1.1 or newer. |
See Choosing the enabled gate and Content Security Policy for the two most common widget fixes.
CLI (@lyba/cli)
| Problem | Likely cause | Fix |
|---|---|---|
lyba: not authenticated | No API key found | Set LYBA_API_KEY, pass --api-key, or run lyba login. |
missing project | No repo slug detected | Pass --project owner/repo or a stable site slug. |
missing preview URL | CI did not expose the preview URL | Pass --preview-url from your deploy step output. |
HTTP 401 | API key is missing, revoked, or from the wrong agency | Rotate/copy a fresh key from Lyba dashboard settings. |
| Review link opens but no overlay appears | @lyba/react missing or disabled | Install the widget and check the enabled gate on the preview build. |
| Review link loses review mode after preview auth | Preview host redirects through SSO | Disable preview protection for clients or use your host's bypass token flow. |
| Toolbar says link is invalid or expired | Token expired, session ended, or CSP blocked Lyba API | Open the durable /r/<slug> Review link again and check connect-src. |
| Comments appear on the wrong deploy | Old review link reused | Run the CLI once per deploy and share the newest Review link. |
See Create sessions from CI for authentication and per-host recipes.
Gotchas checklist
Production safety
enabled must be falsy on prod builds. The widget also self-vetoes when it confidently detects production, and never mounts without a review token — but get the flag right anyway.
CSP
Add https://lyba.io to connect-src. Without it, the toolbar loads but reports that the review link is invalid or has expired, with a connect-src console error.
Preview protection
If previews are gated behind SSO (e.g. Vercel Deployment Protection), external clients can't reach them and the auth redirect drops the review token. Disable protection for previews, or use a bypass token, so a client can open the link in one click.
Per-deploy URLs
Comments are host-checked against the session's preview URL, so create one session per deploy. The CLI is cheap and idempotent on the project: it reuses the project record and creates a new session for the new preview.
Package version
Use @lyba/react@0.1.1 or newer. Version 0.1.0 couldn't be imported by the Next.js App Router.