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).
- Generate review units 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 browser tab saves the walkthrough and notes in
sessionStorage. Restarting the CLI at the same local URL can restore them when the repo, base, branch, scope, and diff match. Ctrl+C stops the server but does not clear that browser data. A changed diff uses a new session key. Copy notes before refreshing a changed diff or switching scope — CLI → Session and refresh. - Starting Guided Review again after a clear rebuilds a new plan for the current diff (How a review plan works).
Successful GitHub submission clears the submitted extension drafts. In the CLI, Generate Prompt copies notes without clearing them. To explicitly clear saved local review data, clear the local URL’s session storage — Privacy & data.
CLI
The diff on disk has changed: Copy notes you need with Generate Prompt, then use the banner’s refresh control. Refresh loads the latest diff; a changed diff starts a fresh walkthrough. AI structuring remains opt-in.
| 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.