Reference
Error code
The list of error codes the CLI prints in the error [code] … format. In your program, branch on code, and use message only for display.
The source of truth for this page is Go source in
cp/internal/public, cp/internal/core, node/internal/front, and node/internal/agent. The docs build generates this content from that source.Reading error responses
All failed API responses use the same structure.
{ "error": { "code": "database_required", "message": "Create a database first" } }The CLI prints this response in the error [database_required] … format and exits with code 1. In automation scripts, branch on code. message is a description for users and can change at any time.
The same code can be returned with different HTTP status codes depending on the situation. When that applies, all of them are listed in the status code column.
Error code list (84)
| Code | HTTP status | Description |
|---|---|---|
access_denied | 401 | The access control bypass secret is incorrect. |
access_exchange_failed | 502 | Access permission check did not complete. Retry shortly. |
access_required | 401 | This deployment has access control configured, so login is required. |
access_unavailable | 503 | The request was not processed because access permission could not be verified. |
active_subscription | 409 | you still have an active paid subscription — cancel it on the billing screen first |
already_member | 409 | The user is already a member of the organization. Change the role with a separate command. |
already_pro | 409 | already on the Pro plan |
artifact_lock_unavailable | 503 | artifact storage can't serialize deploy and teardown |
backend | — | The backend service failed to process the request. |
backup_failed | 503 | Failed to create the database backup. |
bad_request | 400 | The request format is invalid. |
bad_signature | 403 | the webhook signature does not match |
billing_off | 501 | 크레딧 충전이 설정되지 않았다 |
billing_unavailable | 502 | 결제 서비스가 응답하지 않는다 |
bundle_too_large | — | The bundle size exceeds the upload limit. |
cold | 503 | The project is cold and is being restored from a backup. Retry shortly. |
compatibility_date_unsupported | 400 | compatibilityDate … exceeds this runtime's maximum of … — lower the value in runlot.json to … or earlier |
confirm_mismatch | 400 | The confirmation string does not match the project name. |
cron_limit | 400 | the … plan allows up to … scheduled runs per org (currently …, this deployment adds …) |
drain_incomplete | 503 | The switch cannot be made safely because the existing request has not finished processing. |
email_failed | 503 | … |
email_not_declared | 409 | … |
email_rate_limited | 429 | … |
export_failed | 502 · 503 | Failed to export database diagnostics. |
forbidden | 403 | You are authenticated, but you do not have permission to perform this action. |
front_not_ready | 503 | The traffic frontend's initial sync is not complete yet. |
front_unacked | 503 | The traffic frontend has not acknowledged the configuration change. |
git_unavailable | 503 | repository browsing is not enabled |
git_unreachable | 503 | failed to read the repository |
github_token | 502 | Failed to exchange the GitHub token. |
github_user | 502 | Failed to look up GitHub user information. |
grant_failed | 500 | Failed to renew deployment permissions. |
hostname_taken | 409 | This hostname is already in use by another project. |
internal | 500 | An internal server error occurred. Try again shortly. |
invite_expired | 409 | the invite has expired — ask an admin to resend it |
invite_revoked | 409 | the invite has been canceled — ask an admin for a new one |
invite_used | 409 | the invite has already been accepted |
last_admin | 409 | The last admin of the organization. Changing the role leaves no one to manage the organization. |
no_core | 503 | The control plane core service address is not set. |
no_email | 501 | this node cannot receive mail |
no_host | 400 | The request is missing the Host header. |
no_log_buffer | 503 | No log source is configured for the admin API. |
no_payment_method | 409 | 저장된 결제 수단이 없다 — 먼저 한 번 충전하면 그 카드로 자동 충전을 켤 수 있다 |
no_placement | 503 | The project has not been placed on a node yet. |
no_purge | 501 | this node can't tear down the project |
no_ses_hook | 501 | the SES webhook is disabled |
no_wake | 501 | This node cannot start an idle project. |
no_writable_state | 501 | This node has no storage available to perform that database operation. |
node_unreachable | 502 | Cannot connect to the node. Try again shortly. |
not_a_member | 403 | The user is not a member of this organization. |
not_found | 404 | The requested organization, project, or deployment could not be found. |
not_here | 404 | This node cannot handle the requested project. |
not_pro | 409 | not on the Pro plan |
not_ready | 503 | Initial configuration sync is not complete yet. |
op_conflict | 409 | The same operation ID is already in use for another operation. |
op_in_flight | 503 · 409 | The same operation is already in progress. |
org_not_empty | 409 | you can't delete this org because it still holds something — clean up projects, domains, and repositories first |
org_slug_taken | 409 | This organization slug is already in use. |
personal_org | 409 | you can't delete a personal org — this is the org created at your first login |
project_deleting | 409 | the project is tearing down and can't accept new changes |
project_name_taken | 409 | This project name is already in use. |
rate_limited | — | You exceeded the request limit. Try again shortly. |
repo_exists | 409 | repository … already exists |
reserved_name | 400 | This name is reserved and cannot be used. |
restore_busy | 429 | You exceeded the number of restore operations that can run at the same time. |
restore_failed | 500 | Failed to restore the database. |
restore_stalled | 503 | The database restore operation was interrupted. Contact support. |
restore_too_large | 429 | The restore operation exceeded the node's restore capacity limit. |
restoring | 503 | The database is being restored. Try again after it finishes. |
revoked | 403 | Permission for this placement has been revoked. |
seal_failed | 503 | Failed to save the final database generation. |
ssh_key_exists | 409 | this public key is already registered |
suspended | 403 · 409 | The project is suspended. |
unauthorized | 401 | The token is missing or has expired. Run runlot login again. |
unknown | — | An intermediate proxy or similar, not the Runlot server, responded. |
unknown_hostname | 404 | No project connected to that hostname could be found on this node. |
unknown_node | 503 | Could not identify the project's home node address. |
unknown_state | 503 | Unrecognized deployment state. |
unsupported | — | The current storage backend does not support this feature. |
upstream_rate_limited | — | — |
upstream_unreachable | — | Cannot connect to the deployed worker. Check the deployment status. |
user_not_found | 404 | There is no login record for this account. Log in once first. |
wake_failed | 503 | Failed to start the idle project. |
workerd_unchecked | 503 · 500 | Failed to check the commit path state for the worker. |
Errors returned by the running service (56)
This error code is returned when an internal runlot operation, such as placement, restore, or lease management, fails. Most cases resolve if you try again shortly. If the same error continues, contact support.
| Code | HTTP status | Description |
|---|---|---|
already_done | 409 | The requested operation already completed. |
cas_conflict | 409 | The resource state changed, so the request cannot be applied. Check the latest state and try again. |
cert_generation | 403 | The certificate generation used in the request has been revoked. |
claimed | 409 | Another instance is using this database. Try again shortly. |
cname_conflict | 409 | A CNAME record cannot coexist with a record of another type on the same DNS name. |
database_required | 409 | You need a database first. Add "database": true to runlot.json and deploy. |
db_rewound | 409 | The metadata DB was restored to a previous state, so lease issuance stopped. This requires operator recovery action. |
dek_unwrap_failed | 500 | Could not decrypt the project data encryption key. |
dns_not_configured | 503 | The domain cannot be purchased because nameserver setup is not complete. |
dnssec_off | 409 | DNSSEC is disabled for the domain zone. Enable it first. |
domain_taken | 409 | This domain is already registered. |
domain_unavailable | 409 | This domain cannot be registered. |
email_address_taken | 409 | address … is in use by another project |
email_unavailable | 409 | this installation has no mail domain (RUNLOT_MAIL_DOMAIN) — email cannot be enabled |
era_ahead | 409 | The state version (era) in the request is higher than the version stored in the control plane. |
era_write_failed | 500 | Failed to save the state version (era). |
identity_mismatch | 403 | The hostname on the certificate does not match the hostname in the request body. |
invalid_provider | 400 | Unsupported auth provider. |
last_node_unavailable | 503 | The node that held the final database generation is unavailable. |
lease_alive | 409 | The request cannot be processed because the existing lease is still valid. |
lease_drain_pending | 409 | The existing lease is ending. Try again shortly. |
lease_quarantine | 409 | The lease is isolated, so the request cannot be processed. |
lease_seq_ahead | 409 | The lease sequence number in the request is behind the state recognized by the control plane. |
lifecycle_disabled | 503 | Lifecycle operations are disabled. |
managed_rrset | 409 | This is a DNS record managed by Runlot, so you cannot edit it directly. |
master_key_version | 503 | The current control plane does not hold the master key version required for the request. |
no_access_key | 503 | The key for creating access control cookies is not set. |
no_database | 409 | This project has no database connected. |
no_home_node | 503 · 409 | Could not identify the project's home node address. |
no_last_node | 503 | Could not identify the node that held the final database generation. |
no_master_key | 503 | The control plane's master key is not set. |
no_node | 503 | No node is available for placement. |
no_node_admin | 503 | No node admin API address is configured. |
no_object_node | 503 | no active node can delete the project object |
no_session_key | 503 | The key required to connect the login session is not set. |
no_slot | 503 | No capacity is available. Try again shortly. |
node_not_active | 409 | This node is not currently able to perform placement operations. |
not_abortable | 409 | The operation has reached an irreversible stage and cannot be aborted. |
not_active | 409 | This operation cannot be performed in the current state. |
not_cold | 409 | The project is not in a cold state, so the reactivation operation cannot start. |
not_granted | 404 | This project has no auth service connected. |
not_home | 403 · 409 | This node is not the home node for the requested project generation. |
not_quarantined | 409 | The lease is not isolated, so it cannot be activated. |
not_terminal | 409 | The operation is not in a terminal state yet. |
op_stalled | 409 | The operation is in an aborted state. Resolve the cause, then restart it. |
payment_failed | 402 | Payment was not authorized. Check your payment method. |
registrar_error | 502 | The domain registrar returned an error. |
registrar_not_configured | 503 | The domain registrar is not yet connected. |
registrar_rejected | 422 | an earlier purchase of this name was declined: … |
saga_incomplete | 502 | The domain purchase operation did not complete. Send the same request again to continue processing. |
stale_epoch | 409 | This request is for an earlier project generation. Retry with the latest state. |
storage_unavailable | 409 | the node this project is placed on has no file storage backend — an operator needs to attach a backend to the node |
too_large | — | the source exceeds … bytes |
user_rrset | 409 | This is a user-created DNS record, so it cannot be overwritten by a managed record. |
witness_unavailable | 503 | The witness information used to verify the metadata DB state could not be read, so lease issuance or activation was held. |
zone_taken | 409 | This DNS zone already exists. |