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.
On this page›
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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
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) |
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) |
| 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) |
| "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) |
| A reviewer listed as "skipped: |
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) |
| 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) |
/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) |
| "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 |
The credit balance cannot cover that reviewer | Top up, or add your own key (Billing) |
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) |
The review is marked failed and the merge gate 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 |
An Anthropic or OpenAI key with the wrong prefix; nothing was sent | Paste the right key |
| " |
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) |
| "Could not reach |
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 |
The stored key is marked invalid; CodePanel never falls back to another credential | Replace key |
| "No API key for |
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) |
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.
| 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 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 |
A panel edit asked for a provider with no working key | Add the key, or choose another provider |
400 |
" |
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 |
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 |
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).
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) |
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 |
Last updated