Reference
Error codes
Understand CLI's error format and look up what each error code means and what to do about it.
When something goes wrong, CLI's error messages say what happened and what to do about it in plain words, and the dashboard often offers a button that fixes it.
Do you need this page? Only if you write scripts or build agents that handle errors themselves. It lists every error code, what it means, and whether trying again will help.
Every error from CLI has the same shape and a stable code. Agents and scripts should branch on the code, never on the wording of the message, which can change. This page explains the format, what each retry value means, and every code grouped by where it happens.
The error envelope
{
"error": {
"code": "MISSING_ENV",
"message": "The app needs DATABASE_URL, which isn't set",
"remediation": ["Link a database or set the variable, then redeploy"],
"retry": "after_fix",
"details": { "keys": ["DATABASE_URL"] },
"docs": "/v1/errors#MISSING_ENV"
}
}| Field | What it is |
|---|---|
code | The stable error code. Branch on this |
message | A plain explanation for people. Don't parse it |
remediation | Steps to fix it, in order |
retry | Whether and when retrying can work (see below) |
details | Facts about this case, such as the missing keys, the approval id, the DNS problems or how long to wait |
docs | Where this code is described in the catalogue |
A failed deploy carries the same information on the deploy itself (GET /v1/deploys/:id), as error with code, summary, remediation, retry and detail. The detail holds the facts the classifier pulled from the logs, including evidence: the log lines that show the problem.
Payment errors (402) also carry the x402 challenge, in the body and base64-encoded in the PAYMENT-REQUIRED header, so an agent can pay and retry.
Getting the catalogue
From your terminal: failed cli up and cli deploy runs print the code, evidence and remediation.
Ask your agent:
"What does HEALTHCHECK_TIMEOUT mean and how do I fix it?"
Agents use cli_explain_error.
With the API:
GET /v1/errorsThis lists every code with its HTTP status, phase, summary, remediation and retry value. No sign-in needed.
Retry values
| Value | What it means | What to do |
|---|---|---|
yes | A temporary problem | Retry after a pause. For RATE_LIMITED, wait details.retryAfterSeconds. Back off; don't loop |
no | Retrying the same request won't help | Stop and tell the user, or change what you're asking for |
after_fix | Something needs to change first | Fix what remediation says (code, settings, a variable, DNS), then try again |
after_topup | The project or stream needs money | Add credit (the response holds an x402 challenge for the shortfall), then retry |
after_approval | A person has to approve this | Wait for the approval, then resend the identical request with X-CLI-Approval (see /docs/approvals) |
after_step_up | A person has to confirm with their second factor | The person confirms in the dashboard, then the request is resent (see /docs/teams-and-security) |
Requests to the API (phase: api)
Signing in and sessions
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
UNAUTHORIZED | 401 | after_fix | Missing, invalid or expired session token, or a session ended after being idle on a server with an idle timeout (CLI_SESSION_IDLE_MINUTES), or signed out from another device | Sign in again (wallet challenge, email code or a new key) |
AUTH_INVALID_SIGNATURE | 401 | after_fix | The signature doesn't match the address in the challenge | Sign the exact message from /v1/auth/challenge with the same wallet |
AUTH_NONCE_INVALID | 401 | after_fix | The challenge nonce is unknown, already used or expired | Ask for a fresh challenge and sign it within 5 minutes; each nonce works once |
AUTH_CODE_INVALID | 401 | after_fix | The email code or link is wrong, used or expired | Use the code from the latest email, or ask for a new one |
CSRF_INVALID | 403 | after_fix | A browser request with a cookie lacked the matching X-CLI-CSRF header | Send the cli_csrf cookie's value in X-CLI-CSRF; API clients should use a Bearer token |
MFA_CODE_INVALID | 401 | after_fix | The second-factor code or passkey didn't check out | Use the current 6-digit code, a recovery code, or try the passkey again |
MFA_LOCKED | 429 | yes | Too many wrong second-factor attempts | Wait 15 minutes |
STEP_UP_REQUIRED | 403 | after_step_up | This action needs the person to confirm with 2FA or a passkey in the last 10 minutes | Agents: ask the user to confirm in the dashboard. People: POST /v1/auth/step-up, then resend |
MFA_REQUIRED | 403 | no | This needs a person with a second factor set up: the project requires one for changes (see /docs/access-reviews), or the server requires one for operators | Agents: tell the user. People: set up an authenticator app or passkey on your account page, then try again. API keys aren't affected by a project's rule |
Access and requests
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
VALIDATION | 400 | after_fix | The request body or parameters are invalid | Read details for the failing fields and resend |
FORBIDDEN | 403 | no | You're not allowed to do this on this project (role, scope, IP or service list), or, on an operator route, you're not an operator or your operator role (support, finance) doesn't cover it. Some actions need a person rather than an API key, such as deleting a project or account | Ask an admin for access; details.required names what's missing, and on role checks details.role says what you have. For operator routes, an operator admin can change your role (see /docs/compliance) |
NOT_FOUND | 404 | no | The resource doesn't exist or you can't see it. For a project in the trash, details.restorableUntil and details.restore say until when and how an owner can bring it back | Check the id; for a deleted project, see Deleting projects and accounts |
CONFLICT | 409 | after_fix | The resource is in a state that doesn't allow this (for example a sandbox a person is holding) | Read the current state and retry only if the action still makes sense |
RATE_LIMITED | 429 | yes | Too many requests (for example deploys per hour, or sign-in emails) | Wait details.retryAfterSeconds; don't loop |
FEATURE_DISABLED | 501 | no | This feature isn't configured on this CLI server | Use another option (for example x402 instead of card), or ask the operator |
UPSTREAM_FAILED | 502 | after_fix | Something CLI depends on (a database, a secrets manager, a chain) refused or failed | The message says what answered; fix the cause it names. Nothing was changed |
WEBHOOK_SIGNATURE_INVALID | 401 | no | A webhook's signature didn't verify | Check the sender's webhook secret matches the server's |
Approvals
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
APPROVAL_REQUIRED | 403 | after_approval | The project needs a person to approve this first | Tell the user (link in details.approveUrl), poll GET /v1/approvals/:id, then resend the same request with X-CLI-Approval |
APPROVAL_INVALID | 409 | after_fix | The approval doesn't match this request, was denied, used or has expired | An approval covers one exact request by the same agent; resend without the header to ask again |
Domains, GitHub and code
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
DOMAIN_TAKEN | 409 | no | That domain is already attached to a service | Remove it from the other service first, or use another hostname |
DOMAIN_NOT_VERIFIED | 409 | after_fix | The DNS records aren't in place yet | Add the records in details, wait for DNS, verify again (no faster than every 2 minutes) |
GITHUB_NOT_LINKED | 409 | after_fix | No linked GitHub account, or its authorization expired | The user links GitHub (POST /v1/auth/github/link), then installs the CLI GitHub App |
GITHUB_REPO_NOT_ACCESSIBLE | 403 | after_fix | The GitHub App isn't installed on the repo, or your account can't see it | Install the app on the repo; check the owner/name spelling |
SECRETS_IN_UPLOAD | 422 | after_fix | Uploaded code contains secrets (an .env file, a private key or a live API key) | Move values into variables, add the files to .gitignore or .cliignore; details.findings lists files and lines |
Money and payments
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
PAYMENT_REQUIRED | 402 | after_fix | This request needs an x402 payment | Pick an option from accepts[], sign it and resend with PAYMENT-SIGNATURE |
PAYMENT_INVALID | 402 | after_fix | The x402 payment failed verification | Re-sign against the exact amount, payTo, asset and network in the latest 402 |
PAYMENT_REPLAYED | 409 | after_fix | This payment authorization was already used | Sign a new authorization with a fresh nonce |
PAYMENT_SETTLEMENT_FAILED | 502 | yes | The facilitator couldn't settle the payment on chain | Check the wallet has enough USDC on that network, then retry once |
STREAM_EMPTY | 402 | after_topup | The payment stream doesn't have enough left, or is closed | Top it up (POST /v1/streams/:id/topup) or open a new one |
BUDGET_EXCEEDED | 402 | after_fix | The project used its monthly budget, which is set to stop spending | Tell the user; they can raise or remove the budget, or wait until details.resetsAt |
IDENTITY_REQUIRED | 403 | after_fix | This withdrawal passes the amount that needs a verified identity | The person withdrawing verifies once (POST /v1/me/identity); agents never do this for them |
Platform features
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
GPU_UNAVAILABLE | 409 | after_fix | No server has enough free GPUs of that kind | details.capacity lists what's free; ask for fewer or another kind, or join the waitlist with waitForGpu: true |
SIGNER_POLICY | 403 | after_fix | The managed signer's policy doesn't allow this transaction | The message names the rule; nothing was signed. An admin changes the policy if the transaction is right |
SUSPENDED_BY_OPERATOR | 403 | no | The CLI operators suspended this project | GET /v1/projects/:id/abuse shows why; an admin can appeal |
PLACEMENT_REQUIRED | 409 | no | The project keeps everything on its own servers, and this would run on CLI's machines (a service placed elsewhere, or a sandbox) | Move the service with the request in details.fix (PATCH /v1/services/:id {"serverId"}). Sandboxes always run on CLI's machines: an admin can turn off own-servers-only if that's acceptable. See Run in your own cloud |
Before anything starts (phase: preflight)
These come from the checks CLI runs before starting anything that costs money: a deploy's first hour, a sandbox, a paid call.
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
INSUFFICIENT_FUNDS | 402 | after_topup | The balance doesn't cover one hour of what's being started | Pay the x402 challenge in the response (or ask the user to fund the project), then retry |
SPEND_CAP_EXCEEDED | 403 | no | This agent or key reached its spending cap, the project's daily agent limit, or an outbound payment cap | Stop and ask the user to raise the cap. Don't retry |
ACCOUNT_REVIEW | 403 | no | The project is on hold while CLI reviews unusual activity | Stop and tell the user. Don't retry |
PROJECT_SUSPENDED | 402 | after_topup | The project ran out of credit and its services were stopped | Add credit; services restart on their own |
Building (phase: build)
A failed deploy never touches the running version. CLI's classifier reads the logs and returns one code with the evidence line.
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
SOURCE_ACCESS_DENIED | 422 | after_fix | CLI couldn't get access to the source repository | Check the CLI GitHub App is still installed with access to the repo, then redeploy |
IMAGE_PULL_FAILED | 422 | after_fix | CLI couldn't pull the container image | Check the name and tag exist; for private images set registry credentials (GHCR tokens need read:packages) |
BUILD_NO_BUILDER | 422 | after_fix | The builder couldn't tell how to build this source | Add a Dockerfile or a manifest at the root (package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml) |
BUILD_DEP_INSTALL | 422 | after_fix | Installing dependencies failed | Find the package in the evidence; fix the version or name, regenerate the lockfile |
BUILD_COMPILE | 422 | after_fix | The code failed to compile or type-check | Fix the error at the file and line in the evidence |
BUILD_TIMEOUT | 422 | after_fix | The build took longer than the limit | Cache dependencies, skip unneeded steps, or deploy a prebuilt image |
BUILD_OOM | 422 | after_fix | The build ran out of memory | Reduce build parallelism, or move to a larger plan |
CONFIG_INVALID | 422 | after_fix | The cli.json in the repo isn't valid | detail.problems lists each problem and field; fix it or remove the file |
VARIABLE_REFERENCE_MISSING | 422 | after_fix | A variable references a service or variable that doesn't exist | detail.missing lists each ${{service.KEY}} that didn't resolve; fix the name or key |
Starting and releasing (phase: runtime)
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
MISSING_ENV | 422 | after_fix | The app needs a variable that isn't set | Set the variable named in the detail; ask the user for its value, never invent secrets; redeploy |
PORT_MISMATCH | 422 | after_fix | The app isn't listening on the port CLI routes to, or only on localhost | Listen on $PORT and host 0.0.0.0 |
HEALTHCHECK_TIMEOUT | 422 | after_fix | The app started but never answered the health check | Make GET / (or healthcheckPath) return 2xx quickly, or point healthcheckPath at a route that does |
RUNTIME_CRASH | 422 | after_fix | The process exited during startup | Read the stack trace in the evidence and the runtime logs |
RUNTIME_OOM | 422 | after_fix | The app was killed for using more memory than its plan allows | Move to a plan with more memory, or reduce memory use |
RELEASE_COMMAND_FAILED | 409 | after_fix | The release command (usually migrations) failed, so the new version wasn't started | Read its output in the evidence; rehearse on a copy (POST /v1/services/:id/rehearse) |
SMOKE_TEST_FAILED | 409 | after_fix | The new version failed a smoke test, so it never took traffic | The evidence names the request and what came back; fix the app or the test |
CANARY_FAILED | 409 | after_fix | The new version did worse than the live one on a share of traffic, so it was rolled back | details compares error rate and p95; check this deploy's runtime logs |
The current version keeps serving through every one of these.
Anywhere (phase: any)
| Code | Status | Retry | What it means | What to do |
|---|---|---|---|---|
PLATFORM_ERROR | 503 | yes | CLI's infrastructure failed. Not your fault | Retry with backoff, at most 3 times; tell the user if it persists |
UNKNOWN | 422 | after_fix | The failure didn't match a known pattern | Read the deploy's full logs and try a fix; after 2 failed attempts, stop and report the logs |
MCP-only codes
The MCP server can return two codes of its own, LOCAL_SPEND_LIMIT and CLIENT_ERROR. See MCP tools.