Docs menu

Reference

Error codes

Understand CLI's error format and look up what each error code means and what to do about it.

Explain 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

JSON
{
  "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"
  }
}
FieldWhat it is
codeThe stable error code. Branch on this
messageA plain explanation for people. Don't parse it
remediationSteps to fix it, in order
retryWhether and when retrying can work (see below)
detailsFacts about this case, such as the missing keys, the approval id, the DNS problems or how long to wait
docsWhere 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:

API
GET /v1/errors

This lists every code with its HTTP status, phase, summary, remediation and retry value. No sign-in needed.

Retry values

ValueWhat it meansWhat to do
yesA temporary problemRetry after a pause. For RATE_LIMITED, wait details.retryAfterSeconds. Back off; don't loop
noRetrying the same request won't helpStop and tell the user, or change what you're asking for
after_fixSomething needs to change firstFix what remediation says (code, settings, a variable, DNS), then try again
after_topupThe project or stream needs moneyAdd credit (the response holds an x402 challenge for the shortfall), then retry
after_approvalA person has to approve thisWait for the approval, then resend the identical request with X-CLI-Approval (see /docs/approvals)
after_step_upA person has to confirm with their second factorThe 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

CodeStatusRetryWhat it meansWhat to do
UNAUTHORIZED401after_fixMissing, 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 deviceSign in again (wallet challenge, email code or a new key)
AUTH_INVALID_SIGNATURE401after_fixThe signature doesn't match the address in the challengeSign the exact message from /v1/auth/challenge with the same wallet
AUTH_NONCE_INVALID401after_fixThe challenge nonce is unknown, already used or expiredAsk for a fresh challenge and sign it within 5 minutes; each nonce works once
AUTH_CODE_INVALID401after_fixThe email code or link is wrong, used or expiredUse the code from the latest email, or ask for a new one
CSRF_INVALID403after_fixA browser request with a cookie lacked the matching X-CLI-CSRF headerSend the cli_csrf cookie's value in X-CLI-CSRF; API clients should use a Bearer token
MFA_CODE_INVALID401after_fixThe second-factor code or passkey didn't check outUse the current 6-digit code, a recovery code, or try the passkey again
MFA_LOCKED429yesToo many wrong second-factor attemptsWait 15 minutes
STEP_UP_REQUIRED403after_step_upThis action needs the person to confirm with 2FA or a passkey in the last 10 minutesAgents: ask the user to confirm in the dashboard. People: POST /v1/auth/step-up, then resend
MFA_REQUIRED403noThis 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 operatorsAgents: 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

CodeStatusRetryWhat it meansWhat to do
VALIDATION400after_fixThe request body or parameters are invalidRead details for the failing fields and resend
FORBIDDEN403noYou'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 accountAsk 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_FOUND404noThe 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 backCheck the id; for a deleted project, see Deleting projects and accounts
CONFLICT409after_fixThe 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_LIMITED429yesToo many requests (for example deploys per hour, or sign-in emails)Wait details.retryAfterSeconds; don't loop
FEATURE_DISABLED501noThis feature isn't configured on this CLI serverUse another option (for example x402 instead of card), or ask the operator
UPSTREAM_FAILED502after_fixSomething CLI depends on (a database, a secrets manager, a chain) refused or failedThe message says what answered; fix the cause it names. Nothing was changed
WEBHOOK_SIGNATURE_INVALID401noA webhook's signature didn't verifyCheck the sender's webhook secret matches the server's

Approvals

CodeStatusRetryWhat it meansWhat to do
APPROVAL_REQUIRED403after_approvalThe project needs a person to approve this firstTell the user (link in details.approveUrl), poll GET /v1/approvals/:id, then resend the same request with X-CLI-Approval
APPROVAL_INVALID409after_fixThe approval doesn't match this request, was denied, used or has expiredAn approval covers one exact request by the same agent; resend without the header to ask again

Domains, GitHub and code

CodeStatusRetryWhat it meansWhat to do
DOMAIN_TAKEN409noThat domain is already attached to a serviceRemove it from the other service first, or use another hostname
DOMAIN_NOT_VERIFIED409after_fixThe DNS records aren't in place yetAdd the records in details, wait for DNS, verify again (no faster than every 2 minutes)
GITHUB_NOT_LINKED409after_fixNo linked GitHub account, or its authorization expiredThe user links GitHub (POST /v1/auth/github/link), then installs the CLI GitHub App
GITHUB_REPO_NOT_ACCESSIBLE403after_fixThe GitHub App isn't installed on the repo, or your account can't see itInstall the app on the repo; check the owner/name spelling
SECRETS_IN_UPLOAD422after_fixUploaded 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

CodeStatusRetryWhat it meansWhat to do
PAYMENT_REQUIRED402after_fixThis request needs an x402 paymentPick an option from accepts[], sign it and resend with PAYMENT-SIGNATURE
PAYMENT_INVALID402after_fixThe x402 payment failed verificationRe-sign against the exact amount, payTo, asset and network in the latest 402
PAYMENT_REPLAYED409after_fixThis payment authorization was already usedSign a new authorization with a fresh nonce
PAYMENT_SETTLEMENT_FAILED502yesThe facilitator couldn't settle the payment on chainCheck the wallet has enough USDC on that network, then retry once
STREAM_EMPTY402after_topupThe payment stream doesn't have enough left, or is closedTop it up (POST /v1/streams/:id/topup) or open a new one
BUDGET_EXCEEDED402after_fixThe project used its monthly budget, which is set to stop spendingTell the user; they can raise or remove the budget, or wait until details.resetsAt
IDENTITY_REQUIRED403after_fixThis withdrawal passes the amount that needs a verified identityThe person withdrawing verifies once (POST /v1/me/identity); agents never do this for them

Platform features

CodeStatusRetryWhat it meansWhat to do
GPU_UNAVAILABLE409after_fixNo server has enough free GPUs of that kinddetails.capacity lists what's free; ask for fewer or another kind, or join the waitlist with waitForGpu: true
SIGNER_POLICY403after_fixThe managed signer's policy doesn't allow this transactionThe message names the rule; nothing was signed. An admin changes the policy if the transaction is right
SUSPENDED_BY_OPERATOR403noThe CLI operators suspended this projectGET /v1/projects/:id/abuse shows why; an admin can appeal
PLACEMENT_REQUIRED409noThe 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.

CodeStatusRetryWhat it meansWhat to do
INSUFFICIENT_FUNDS402after_topupThe balance doesn't cover one hour of what's being startedPay the x402 challenge in the response (or ask the user to fund the project), then retry
SPEND_CAP_EXCEEDED403noThis agent or key reached its spending cap, the project's daily agent limit, or an outbound payment capStop and ask the user to raise the cap. Don't retry
ACCOUNT_REVIEW403noThe project is on hold while CLI reviews unusual activityStop and tell the user. Don't retry
PROJECT_SUSPENDED402after_topupThe project ran out of credit and its services were stoppedAdd 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.

CodeStatusRetryWhat it meansWhat to do
SOURCE_ACCESS_DENIED422after_fixCLI couldn't get access to the source repositoryCheck the CLI GitHub App is still installed with access to the repo, then redeploy
IMAGE_PULL_FAILED422after_fixCLI couldn't pull the container imageCheck the name and tag exist; for private images set registry credentials (GHCR tokens need read:packages)
BUILD_NO_BUILDER422after_fixThe builder couldn't tell how to build this sourceAdd a Dockerfile or a manifest at the root (package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml)
BUILD_DEP_INSTALL422after_fixInstalling dependencies failedFind the package in the evidence; fix the version or name, regenerate the lockfile
BUILD_COMPILE422after_fixThe code failed to compile or type-checkFix the error at the file and line in the evidence
BUILD_TIMEOUT422after_fixThe build took longer than the limitCache dependencies, skip unneeded steps, or deploy a prebuilt image
BUILD_OOM422after_fixThe build ran out of memoryReduce build parallelism, or move to a larger plan
CONFIG_INVALID422after_fixThe cli.json in the repo isn't validdetail.problems lists each problem and field; fix it or remove the file
VARIABLE_REFERENCE_MISSING422after_fixA variable references a service or variable that doesn't existdetail.missing lists each ${{service.KEY}} that didn't resolve; fix the name or key

Starting and releasing (phase: runtime)

CodeStatusRetryWhat it meansWhat to do
MISSING_ENV422after_fixThe app needs a variable that isn't setSet the variable named in the detail; ask the user for its value, never invent secrets; redeploy
PORT_MISMATCH422after_fixThe app isn't listening on the port CLI routes to, or only on localhostListen on $PORT and host 0.0.0.0
HEALTHCHECK_TIMEOUT422after_fixThe app started but never answered the health checkMake GET / (or healthcheckPath) return 2xx quickly, or point healthcheckPath at a route that does
RUNTIME_CRASH422after_fixThe process exited during startupRead the stack trace in the evidence and the runtime logs
RUNTIME_OOM422after_fixThe app was killed for using more memory than its plan allowsMove to a plan with more memory, or reduce memory use
RELEASE_COMMAND_FAILED409after_fixThe release command (usually migrations) failed, so the new version wasn't startedRead its output in the evidence; rehearse on a copy (POST /v1/services/:id/rehearse)
SMOKE_TEST_FAILED409after_fixThe new version failed a smoke test, so it never took trafficThe evidence names the request and what came back; fix the app or the test
CANARY_FAILED409after_fixThe new version did worse than the live one on a share of traffic, so it was rolled backdetails compares error rate and p95; check this deploy's runtime logs

The current version keeps serving through every one of these.

Anywhere (phase: any)

CodeStatusRetryWhat it meansWhat to do
PLATFORM_ERROR503yesCLI's infrastructure failed. Not your faultRetry with backoff, at most 3 times; tell the user if it persists
UNKNOWN422after_fixThe failure didn't match a known patternRead 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.