Error code reference
vastframe errors teach. Every error has a stable code and a human message; SDK errors also carry a fix.
- REST API errors look like
{ "error": { "code": "READ_ONLY", "message": "…" } }with an HTTP status. - SDK errors are
TcErrorinstances with.codeand.fix(JavaScript), or raisedTcError(Python).tc.storageandtc.db.from()return{ data, error }instead of throwing. - CLI prints
CODE: messageand exits with status 1. - MCP tools return the same code and message to the agent.
Sign-in and access
| Code | Status | Meaning |
|---|---|---|
UNAUTHORIZED / UNAUTHENTICATED | 401 | Not signed in. Sign in through the console, or tc login --dev locally |
NO_ACCESS | 403 | Signed in, but not allowed to open this app; the fix names the owner |
FORBIDDEN | 403 | Your role doesn't allow this action |
READ_ONLY | 403 | You have read-only access, for example as an Auditor |
ADMIN_ONLY | 403 | Only an Org Admin can do this |
NOT_A_BUILDER | 403 | Creating projects is limited to Builders in your organization |
PROJECT_NOT_FOUND / NOT_FOUND | 404 | No such project, or you can't see it (projects you can't see answer 404, not 403) |
Projects and deploys
| Code | Status | Meaning |
|---|---|---|
INVALID_NAME | 400 | The project name doesn't follow the naming rules |
NAME_TAKEN | 409 | Another project already has that name |
NAME_BEING_FREED | 409 | A project with that name was just deleted; try again in a few seconds |
BAD_BUNDLE, EMPTY_BUNDLE, NO_SOURCE | 400 | The uploaded source couldn't be read or was empty |
BUNDLE_TOO_LARGE | 413 | Source bundles are limited to 50 MB |
TOO_LARGE_FOR_MCP | 413 | MCP upload_file takes files up to 5 MB; use tc storage put for bigger files |
PURPOSE_REQUIRED | 400 | MCP deploy: the code uses an integration that needs approval; add a one-line purpose |
DEPLOYMENT_NOT_FOUND, NO_DEPLOYMENTS | 404/409 | No such deployment, or the project has none yet |
NO_ROLLBACK_TARGET | 409 | There is no earlier ready deployment to roll back to |
NOT_READY, NO_PRODUCTION | 409 | The deployment isn't ready, or nothing serves production yet |
CONFIRM_MISMATCH | 400 | Delete: the confirmation doesn't match the project name |
PROJECT_DISABLED, PROJECT_NOT_ACTIVE | 409 | The project is disabled by IT or archived |
LICENSE_EXPIRED | 402 | Deploys are paused: the licence expired past its grace period (running apps keep serving) |
LICENSE_LIMIT | 402 | New projects are paused: the licence's project cap is reached, or it expired past its grace period |
LICENSE_FEATURE | 402 | The feature isn't included in your licence |
Settings
| Code | Status | Meaning |
|---|---|---|
INVALID_ENV | 400 | A variable name is reserved or invalid, or the value is too large |
TOO_MANY_ENV | 400 | More than 100 variables |
ENV_NOT_FOUND | 404 | No such variable |
STATIC_SITE | 409 | Static sites have no runtime, so there's nothing to redeploy with variables |
INVALID_ACCESS, INVALID_MEMBER, INVALID_ROLE, UNKNOWN_PRINCIPAL | 400 | An access rule names an unknown person, group or invalid role |
Database
| Code | Meaning |
|---|---|
SQL_TIMEOUT | The query ran longer than the statement timeout |
READ_ONLY | A write in read-only mode |
PERMISSION_DENIED | Postgres refused the operation |
SQL_ERROR | Any other Postgres error, with its message |
TABLE_NOT_FOUND, COLUMN_NOT_FOUND | No such table or column |
DB_PROVISIONING | The project database is still being created; retry shortly |
DB_ERROR | SDK: a database error; details.code is the SQLSTATE |
NO_REQUEST | SDK: server code made a per-person call without the request |
SERVER_ONLY | SDK: tc.db.sql and similar calls are server-only |
NOT_CONFIGURED | SDK: the platform environment isn't present (for example running outside vastframe) |
Storage
| Code | Meaning |
|---|---|
STORAGE_QUOTA_EXCEEDED | The project's storage is full |
STORAGE_FILE_TOO_LARGE | The file is over the per-file limit |
STORAGE_TYPE_NOT_ALLOWED | The file type isn't allowed |
STORAGE_EXISTS | A file exists at that path; pass upsert: true |
STORAGE_NOT_OWNER | Only the uploader, an editor or an admin may change it |
STORAGE_FORBIDDEN | Someone else's file in a private bucket |
STORAGE_NOT_FOUND, STORAGE_BUCKET_NOT_FOUND | No such file or bucket |
STORAGE_NOT_PUBLIC | getPublicUrl on a private bucket |
STORAGE_SIGNATURE_EXPIRED | The signed URL has expired |
INVALID_BUCKET, INVALID_VISIBILITY | Bad bucket name or visibility |
BUCKET_NOT_EMPTY | Deleting a bucket that still has files without forcing it |
PROJECT_ARCHIVED, PROJECT_DISABLED | Storage is paused while the project is archived or disabled |
Integrations
| Code | Meaning |
|---|---|
ACCESS_PENDING | The grant is waiting for approval; err.request has the request id, approvers and URL. Works once approved, no redeploy |
ACCESS_DENIED | Refused, or approved narrower than the call needs |
CONNECT_REQUIRED | The person must connect their account (err.connectUrl, tc.int.<name>.connect()) |
VENDOR_ERROR | The vendor answered with an error; err.details has its body |
M365_ACCESS_DENIED | The person can't open the Microsoft 365 file |
INTEGRATION_NOT_FOUND | No such integration in your catalog |
REQUEST_NOT_FOUND | No such access request |
Sign-in configuration (admins)
| Code | Meaning |
|---|---|
IDP_UNREACHABLE | The identity provider's discovery document couldn't be fetched |
IDP_INVALID | The discovery document is invalid or its issuer doesn't match |
INSTALLATION_SIGN_IN | The default organization uses the installation's own sign-in, which isn't changed here |
NOT_VERIFIED, NO_VERIFIED_DOMAIN | The email domain isn't verified yet |
WORKOS_NOT_CONFIGURED, WORKOS_NOT_ENABLED | Enterprise SSO isn't set up for the installation or this organization |
DIRECTORY_READ_ONLY | People are synced from a directory, so they can't be edited by hand |
Was this page helpful?