Troubleshooting
Straight fixes for the problems that show up most often. If something fails, read the message in Options or the overlay first — provider and GitHub errors are often already specific enough to act on.
Concept overviews: How a review plan works · FAQ · Privacy & data.
No Start Guided Review button
- Confirm the tab is a pull request URL on
github.com(Conversation, Files changed, or Commits) — same as Your first review. - Reload the page. SPA navigations from the PR list should still inject the button; a full reload clears stuck DOM.
- Check the extension is enabled and allowed on GitHub in
chrome://extensions. - If you loaded unpacked, confirm you selected
apps/extension/dist, then Reload the extension and refresh the tab (Install).
Provider and API key
| Symptom | What to try |
|---|---|
| Prompted for a key on start | Open Options → configure a provider → paste a valid key → Save |
| Test connection fails | Wrong key or model, expired key, or network/VPN blocking the provider. Fix the key, pick a model your account can use, retry |
| Auth / invalid key from the provider | Regenerate the key in the provider console; don’t paste org-restricted keys your seat can’t use |
Keys live only in chrome.storage.local and leave the machine toward your provider when annotating — not toward Guided Review servers (Privacy & data).
Plan generation fails
- Mid-stream error — Check the overlay message. Common causes: rate limits, insufficient quota, model unavailable, or a network blip. Wait and retry, or switch model/provider in Options.
- Empty or thin plan — Very large or mostly binary PRs produce less useful structure. Chunking still runs by file; binary/elided files won’t get textual units.
- Lost connection to the worker — Reload the extension and the PR tab, then start again (first review).
The model only supplies order and commentary (How a review plan works). If hunks don’t match the real diff, those refs are dropped rather than shown as broken code.
GitHub connect and submit
| Symptom | What to try |
|---|---|
| Device flow never completes | Finish the code at GitHub’s verification URL before it expires; don’t close Options mid-flow — device flow steps |
| Org blocks the OAuth app | An org admin must approve the app, or complete the review on github.com |
| Submit returns 401 / reconnect | Disconnect and connect again in Options so a fresh token is stored |
| Submit returns 403 | Your user can’t review that PR, or the token lacks access (scopes) |
| Submit returns 404 | PR gone or inaccessible; for private org repos also check SSO |
| Submit returns 422 | Line comments no longer match the current diff — re-draft on the latest plan |
See Connect GitHub for scopes and disconnect, and Submit a review for the happy path.
Private repos and SSO
- Diff fetch and submit use your browser session / token as appropriate. Private PR access follows whatever GitHub already allows for your account.
- Many orgs require SSO authorization on third-party tokens. If submit fails with not-found or access errors on a private org repo:
- Open GitHub → Settings → Applications (or the org’s SSO prompt).
- Authorize the Guided Review / OAuth token for that organization.
- Retry submit, or reconnect GitHub in Options if needed.
Narrative version: Connect GitHub → Private repos and org SSO.
Session and resume
- Active plans live in
chrome.storage.session, keyed byowner/repo#number. Switching Conversation ↔ Files changed should resume the same step (Your first review → Resume later). - Closing the browser (or ending the session) clears the plan. Settings and API keys in local storage remain (Privacy & data).
- Starting Guided Review again on the same PR after a clear rebuilds a new plan for the current diff (How a review plan works).
Draft comments are part of the same session until you submit or discard them (Leave line comments).
Load unpacked / stale build
If you develop from source:
- Run
npm run build:extensionfrom the monorepo root after code changes. - In
chrome://extensions, hit Reload on the Guided Review card. - Refresh the GitHub PR tab.
Chrome loads apps/extension/dist, not a root-level dist/. A stale folder means you keep seeing old behavior even with npm run dev running. Full install steps: Install → Load unpacked.