# Troubleshooting

URL: https://codepanel.ai/docs/troubleshooting

Fixes by symptom: reviews that did not run or failed, spending refusals, key and connection errors, API and MCP errors, and the merge gate.

Messages are quoted as CodePanel shows them, so you can search this page for the text you see. `<provider>`, `<model>` and `<sha>` stand for the values in your message.

## Reviews

| What you see | Cause | Fix |
| --- | --- | --- |
| Nothing happens on a new pull request | **Review automatically** is off, or that event is turned off | Check **Automatic reviews** on the repository's **Settings** tab ([Triggering reviews](/docs/triggering-reviews#change-the-triggers)) |
| Nothing happens on a draft | Drafts are not reviewed by default | Mark it ready, turn on **Include drafts**, or comment `/review` |
| Nothing happens on a bot's pull request | Bot authors are skipped | Comment `/review` |
| Nothing happens on a fork's pull request | Its author is not an owner, member or collaborator | Have someone with write access comment `/review` |
| `/review` does nothing | The commenter is not an owner, member or collaborator | Ask someone with write access |
| A command gets 👎 and a `Refused:` reply | `write_permission_required`: the commenter lacks write access. `permission_check_failed`: GitHub did not confirm it | Ask someone with write access, or repeat the command in a few minutes ([who may give commands](/docs/commands#who-may-give-commands)) |
| Nothing happens for one base branch | The base branch is filtered out | Adjust **Branches** on the repository's **Settings** tab |
| Nothing happens on any pull request | The repository is disconnected | Connect it again |
| A push is not reviewed, and the commit was already reviewed or is being reviewed | Each commit is reviewed once | Nothing to do |
| Pushes stop being reviewed | The pull request reached its automatic round limit | Comment `/review` or choose **Start** for another round, comment `/rounds +1` to review the latest push, or raise or clear the limit ([PR commands](/docs/commands#rounds)) |
| **Start** fails with "Add a working provider API key in Settings → Provider keys first." | No stored key works, so no panel can be built | Add or replace a key under **Settings → Provider keys** ([Providers and keys](/docs/providers-and-keys#invalid-or-missing-keys)) |
| The session fails with "No review panel configured, and no working provider API key to build one from. Add a key in Settings." | The same, for a review started by a webhook | Add or replace a key |
| **Start** fails with "GitHub token not configured. Reconnect GitHub and try again." | CodePanel has no usable GitHub token for you | Sign out and sign in again |
| The session fails with "No reviewer has a working API key." or "The orchestrator cannot run:" and a reason | No reviewer, or not the orchestrator, has a working key | Fix the key the reason names ([Providers and keys](/docs/providers-and-keys#invalid-or-missing-keys)) |
| The session fails with "Every reviewer failed." and each reviewer's error | Every reviewer's provider call failed, after up to 3 retries each | Fix what the errors name, often provider credit, then comment `/review` |
| The session fails with "Review timed out" | The round stalled past its 10-minute limit | Comment `/review` ([How it works](/docs/how-it-works#deadlines)) |
| A review is `failed` | A failure on CodePanel's or the provider's side, not a verdict on the code | Read the reason with `GET /api/v1/sessions/get` or the session in the dashboard |
| GitHub's **Redeliver** does not re-run a review | The delivery id was already recorded; the answer is `200 Duplicate delivery` | Comment `/review` or choose **Start**. Redelivering a rejected delivery (such as a `401`) works |

### Webhook deliveries

To see why GitHub's delivery was refused, open the repository on GitHub, then **Settings → Webhooks**, CodePanel's webhook, **Recent Deliveries**. CodePanel's response body names the reason:

| Response | Cause | Fix |
| --- | --- | --- |
| `Commenter not permitted` | The commenter is not an owner, member or collaborator | Ask someone who is |
| `Pull request from an untrusted fork` | The fork's author is not an owner, member or collaborator | Have someone with write access comment `/review` |
| `Not a command` | The comment holds no command CodePanel reads | Nothing to do |
| `Repository not active` | The repository is disconnected or inactive | Connect it again |
| `401 Invalid signature` | The signature does not match the repository's secret, the repository is unknown, or it has no secret | If the delivery came from CodePanel's own webhook, reinstall it from the repository's **Settings** tab ([Security](/docs/security#webhooks)) |
| `429` with `Retry-After` | Over 60 verified deliveries per minute for the repository | Wait a minute; comment `/review` if a review was missed |

## Pull request comment

| What you see | Cause | Fix |
| --- | --- | --- |
| "Review of `<sha>` skipped:" and a reason | A spending limit was reached; no review of that push follows | Raise or remove the limit under **Settings → Budget** or the repository's **Spend & budget** tab, then comment `/review` ([Budgets and limits](/docs/budgets-and-limits#refusals)) |
| A reviewer under "Failed this round, so not part of this review" | Its provider call failed, often because the provider account is out of credit. The others still posted | Add credit or create a new key, then **Replace key** or **Refresh models** ([Providers and keys](/docs/providers-and-keys#keys-that-stop-working)) |
| "Timed out: the round went on without this reviewer" | The reviewer was still running at the reviewer deadline | If it recurs, choose a faster model or lower reasoning effort for that reviewer ([Reviewers and panels](/docs/reviewers#reasoning-effort)) |
| A reviewer listed as "skipped: <provider> key out of credit or revoked since …" | Two rounds in a row failed on your key with an out-of-credit or revoked-key error, so CodePanel turned the key off | Add credit or create a new key, then **Replace key** or **Refresh models** to turn it back on ([Providers and keys](/docs/providers-and-keys#keys-that-stop-working)) |
| A reviewer under **Needs attention** on the home page, or marked **Failing** on the reviewers page | It failed two rounds in a row | Fix its key, or switch it to another model; the mark clears on its next successful round |
| Files listed as not reviewed | Lock, generated, minified, snapshot and binary files, patches over 20,000 characters, and what does not fit the 120,000-character round budget are skipped | Expected ([How it works](/docs/how-it-works#file-triage)) |
| `/ask`, `/remember` or an unreadable reply in an inline suggestion's thread gets no answer | The repository webhook was installed before CodePanel subscribed to pull request review comments | Run `codepanel repos connect <owner/name>` or the MCP tool `connect_repo` again, or reinstall the webhook on the repository's **Settings** tab |

## Spending limits and credits

| What you see | Cause | Fix |
| --- | --- | --- |
| "Your account's monthly budget of $X has been reached ($Y spent this month across your repositories). Change or remove it in CodePanel → Settings → Budget." (or "default monthly budget of $25.00") | The account's monthly budget is spent | Raise or remove it under **Settings → Budget**, in the app only ([Budgets and limits](/docs/budgets-and-limits#set-the-limits)) |
| "The monthly cap of $X for owner/repo has been reached ($Y spent this month). Change or remove it in CodePanel → Repository → Spend & budget." | The repository's cap is spent | Raise or remove it on the repository's **Spend & budget** tab |
| "Spending limit of $X reached for this pull request ($Y spent); review skipped." | The per-PR limit is spent | Raise or clear it under **Limits** on **Spend & budget**, or with `codepanel panel set --budget` |
| "Not enough CodePanel credits for this review. Top up in Settings → Billing, or add your own <provider> key." | The credit balance cannot cover that reviewer | Top up, or add your own key ([Billing](/docs/billing#running-low-on-credits)) |
| `errorCode` `plan_required`, `plan_limit`, `credits_required`, `credits_exhausted`, `provider_key_missing` or `provider_key_invalid` | No plan, the plan's monthly pull requests used up, or the panel cannot run on keys or credits | Follow `nextAction` ([Billing](/docs/billing#when-a-review-is-refused)) |

The review is marked `failed` and the [merge gate](/docs/merge-gate#reviews-paused) judges the commit on the findings it already has, with reviews paused: an agent's answers count as given, and only a finding nobody answered (or an upheld dispute) fails it.

## Keys and providers

| What you see | Cause | Fix |
| --- | --- | --- |
| "That doesn't look like a <provider> key (expected <format>)." | An Anthropic or OpenAI key with the wrong prefix; nothing was sent | Paste the right key |
| "<provider> requires a base URL." | The custom provider needs one | Enter the base URL |
| "That isn't a Cloudflare account ID. …" | The Workers AI field holds neither a 32-character account ID nor a URL that contains one | Paste the account ID from the Cloudflare dashboard |
| "Base URL must start with http:// or https://" | The base URL has no scheme | Add it |
| "That base URL points at a local address, which is not allowed." (or "a private address", or "resolves to a private address") | The base URL targets a non-public network | Use a public address ([Providers and keys](/docs/providers-and-keys#custom-base-url)) |
| "Could not reach <url>: <error>" | The models endpoint did not answer within 15 seconds, or the connection failed | Check the URL and that the endpoint is up |
| "The endpoint responded but did not return JSON. Check the base URL." | The base URL points at something other than an API | Fix the base URL |
| "The key works but no usable chat models are available to it." | The key reaches no chat model CodePanel can use | Use a key with chat model access |
| The provider's own error on save | The provider rejected the key, for example because it was revoked | Create a new key |
| "The <provider> API key is invalid. Update it in Settings." | The stored key is marked invalid; CodePanel never falls back to another credential | **Replace key** |
| "No API key for <provider>. Add one in Settings." | The panel uses a provider you have no key for | Add a key, or change the reviewer's model |
| A key shows as valid but its reviewer fails | Stored keys are not re-checked on a schedule, and a failed review call does not change their status | **Refresh models** on the provider's row to re-check it |
| Workers AI reviewers are slowed or rejected | Each frontier `@cf/` model that needs the Workers Paid plan allows 20 requests a minute, shared by every reviewer on it | Mix models, or put one or two reviewers on each |
| No **Connect ChatGPT plan** in Settings, or "ChatGPT plan connections are turned off on this deployment. Add an OpenAI API key instead." | The deployment has not turned the ChatGPT plan on | Use an OpenAI API key ([ChatGPT plan](/docs/chatgpt-plan)) |

## Agent connection

Ask the agent: "Use the CodePanel whoami tool." It should answer with your GitHub account and its permissions. The full table is in [Connect your agent](/docs/coding-agents#troubleshooting).

| What you see | Cause | Fix |
| --- | --- | --- |
| "Needs authentication" or `401` | The sign-in lapsed, or the token is missing, mistyped, revoked or expired | Sign in again from the agent's MCP menu, or create a new token |
| A tool says it needs a permission | You unticked it on the consent page, or the token lacks the scope | Reconnect and approve it, or create a token with it |
| "this is a CI token" | CI tokens work only for the merge gate | Use a personal token or sign in |
| "not found" for a repository you own | You signed in as a different GitHub account, or the repository is not connected | Sign in as the right account, or connect the repository |
| The tools do not appear | The agent has not reloaded its MCP config | Restart the agent or the session |
| "rate limit exceeded" | Too many calls in a short time | Wait and retry |

## API and MCP errors

Branch on `code`, which is stable; `error` is for people and may be reworded. Relay a `400` message to a person instead of retrying. Details are in the [HTTP API](/docs/api#limits-and-errors) reference.

| Status | What you see | Cause | Fix |
| --- | --- | --- | --- |
| `400` | "Add a working provider API key in Settings → Provider keys first." | No provider key works | A person adds one in the browser |
| `400` | "GitHub token not configured. Reconnect GitHub and try again." | The token owner's GitHub token is missing | The token owner signs in to CodePanel again |
| `400` | "No working API key for <provider>. Add one in Settings first." | A panel edit asked for a provider with no working key | Add the key, or choose another provider |
| `400` | "<model> is not available to your <provider> key. Refresh the model list in Settings." | The model id is not one the key reaches | Use a model id exactly as `GET /api/v1/models` lists it |
| `400` | `code` `precondition` with a `reason` | Something must change first, such as `credits_required` | See [Billing](/docs/billing#when-a-review-is-refused) |
| `400` | "request body must be JSON", "request body must be a JSON object", or a field error such as "repo must be owner/name" | Malformed request (`invalid_input`) | Fix the request; retrying it unchanged fails again |
| `401` | "missing bearer token" | No token sent | Send `Authorization: Bearer <token>` |
| `401` | "not a CodePanel API token; create one in Settings → API tokens" | Not a CodePanel token, for example a webhook secret | Create a personal token |
| `401` | "invalid, revoked or expired token" | The token no longer works | Create a new token, or sign in again |
| `403` | "this token lacks the <scope> scope" | `missing_scope`; `scope` names it | Create a token with that scope, or reconnect and approve it |
| `403` | "this is a CI token for one repository; create a personal token in Settings → API tokens" | A CI token used outside the review it reads | Use a personal token |
| `404` | `not_found` | The thing does not exist or is not yours; both get the same answer | Check the repository, pull request or id, and which account you signed in as |
| `413` | Request body too large | Over 65,536 characters | Send less |
| `429` | "rate limit exceeded" | Over 120 requests a minute, or 20 review triggers an hour, per token | Wait the seconds in `retry-after` (`retryAfter` in the body) |
| `500` | `{"error":"internal error"}` | A server failure | Retry later |

Over MCP, a failure is a tool error that starts with `CodePanel:` and carries the server's message. When there is a `code`, a second text block holds the JSON, such as `{"error": "this token lacks the reviews:write scope", "code": "missing_scope", "scope": "reviews:write"}` ([MCP server](/docs/mcp-server#errors)).

## Merge gate

| What you see | Cause | Fix |
| --- | --- | --- |
| A new commit has no `CodePanel` status for about a minute | Pushes wait 60 seconds before review | Wait; a required check waits too ([Merge gate](/docs/merge-gate#status-behaviour)) |
| `CodePanel` is not offered as a required check | GitHub lists it only after it has been posted once | Let one pull request be reviewed, then add it |
| **Status not posting** on the dashboard, `gate.status` is `missing_permission`, or the review comment says what to accept | The GitHub App lacks **Commit statuses: Read and write** | Accept the permission on the installation; the status posts on the next change |
| `gate.status` is `refused` | GitHub did not take the status | The pull request carries no status; read `gate.blocking` from `GET /api/review` instead |
| No status at all | The gate level is `off` | Set a gate level under **Settings → Review gate** |
| The gate passes with a warning while critical findings are open | The latest round failed or was refused by a spending limit, so the review is `failed` | Fix the cause and comment `/review` |
| The Actions gate fails at once with `401` `{"error":"missing bearer token"}` | The `CODEPANEL_TOKEN` secret is missing | Add it |
| The Actions gate fails at once with `403` `{"error":"not authorized"}` | A wrong token, a token for another repository, or an unknown repository | Create a CI token on that repository's **Settings** tab |
| `400` `{"error":"repo must be owner/name and pr a positive integer"}` | Bad query parameters | Fix `repo` and `pr` |
| The Actions gate always takes 15 minutes | `CODEPANEL_URL` is wrong | Use your Convex site URL, ending in `.convex.site` |
| The Actions gate still fails after you answered findings | The workflow runs on pushes only | Re-run it; the `CodePanel` status updates by itself |