Troubleshooting
Straight fixes for the problems that show up most often. If something fails, read the message in Options, the overlay, or the CLI terminal 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. Hosts other than github.com are not supported by the extension (FAQ); use the CLI for local git instead. - Avoid PR sub-pages that aren’t review surfaces — for example conflict resolution (
…/pull/N/conflicts). The extension intentionally does not inject there; open Conversation, Files changed, or Commits instead. The toolbar popup says so when the active tab is one of those paths. - 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. Reload the extension from that page, then refresh the PR tab.
If the on-page button is missing but the PR URL is valid, try the toolbar icon while that tab is active (Chrome Extension → After install).
Provider and API key
| Symptom | What to try |
|---|---|
| Prompted to connect a provider | Extension: Options → configure a provider → paste a valid key → Save. CLI: Settings (⌘/Ctrl + ,) or env / --provider. You can still walk file by file without a key |
| 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 |
| CLI “Use My Subscription” fails | Agent not logged in, or the unofficial key path broke. Prefer a console API key in Settings or env |
Extension keys live in chrome.storage.local. CLI keys live in env, flags, or ~/.config/guided-review/config.json. Both leave the machine toward your provider when annotating — not toward Guided Review servers (Privacy & data).
Plan generation fails
- Mid-stream error — Check the overlay or CLI message. Common causes: rate limits, insufficient quota, model unavailable, or a network blip. Wait and retry, or switch model/provider.
- Empty or thin plan — Very large or mostly binary diffs produce less useful structure. Chunking still runs by file; binary/elided files won’t get textual units.
- Lost connection to the worker (extension) — Reload the extension and the PR tab, then start again (first review).
- Structure With AI does nothing (CLI) — Confirm a key is available (Configure AI provider → CLI), then retry. Check the terminal log below the banner for the error.
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
Extension-only. The CLI does not submit to GitHub.
| 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
- Extension: 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). - CLI: The session lives with the running local server. Stopping the process (Ctrl+C) ends it. Restarting
npx @guided-review/clistarts a fresh walk for the current scope. - Starting Guided Review again after a clear rebuilds a new plan for the current diff (How a review plan works).
Draft comments (extension) and notes (CLI) are part of that session until you submit, Generate Prompt, discard them, or stop the host.
CLI
| Symptom | What to try |
|---|---|
npx guided-review does the wrong thing | Use the scoped package: npx @guided-review/cli. The hyphenated unscoped name is a different tool |
| Port already in use | Pass --port (or --port 0 for any free port), or stop the other process on 7182 |
Nothing to review against <base>. | Empty scopes — commit, stage, or pass --base / pick another scope in the UI (CLI) |
| Not a git repository | Run from inside a git repo, or pass a repo path as the first argument |
| Browser doesn’t open | Open the URL printed in the banner, or drop --no-open |
| Structure / Settings can’t find a key | Configure AI provider → CLI; check env vars and ~/.config/guided-review/config.json |
Full local workflow: CLI.