# Toupas error codes

Errors carry `code`, `message` (plain words for the user), `hint`, and often `agentInstructions` (for you) and `askUser` (a question for the user). When they're there, follow them; this list is the fallback.

| Code | What to do |
|---|---|
| `E_ACCESS_DENIED` | The user cancelled the sign-in in their browser. Ask whether they want to sign in, then try again. |
| `E_ACCOUNT_SUSPENDED` | Toupas suspended this account; nothing can be made live or changed. Tell the user the reason in the message and that they can write to hello@toupas.com. Don’t retry. |
| `E_ADDON_IN_USE` | That extra RAM or storage is in use; free it first. |
| `E_APP_CRASHED` | The app stopped right after starting. Read its last log lines, fix the cause, and make it live again. |
| `E_APP_HEALTH_CHECK` | The app started but didn’t answer its health check. It must listen on 0.0.0.0:$PORT; check healthCheck.path. |
| `E_APP_OUT_OF_MEMORY` | The app used more memory than it has. Reduce its memory use, or raise `memoryMb` (counts toward the account’s RAM). |
| `E_APP_START_TIMEOUT` | The app didn’t start in time. It must listen on 0.0.0.0:$PORT; slow start-up tasks can raise healthCheck.timeoutSeconds. |
| `E_APP_UNKNOWN` | Toupas couldn’t tell what kind of app this is. Add a `toupas.json` (toupas://docs/toupas-json), or check you’re in the app’s folder. |
| `E_ARCH_UNSUPPORTED` | The prepared app is for the wrong processor. Make it live again with this Toupas program, which prepares it for Toupas’s servers. |
| `E_AUTHORIZATION_PENDING` | The user hasn’t approved the sign-in link yet. Wait for them, then try again. |
| `E_BILLING_COUNTRY_REQUIRED` | The user chooses their country on the payment page first. |
| `E_BILLING_NOT_CONFIGURED` | Payments aren’t open yet. Tell the user. |
| `E_BINARY_PLATFORM` | A dependency has a native part built for another system. Make it live again (it’s prepared in Toupas’s builder), or replace the dependency. |
| `E_BUILD_FAILED` | The app’s own build failed; its output is in the error. Fix the code so the build passes on this computer, then make it live again. |
| `E_BUILDER_PULL` | Docker couldn’t download Toupas’s builder. Check the internet connection and that Docker Desktop is running, then try again. |
| `E_BUILDER_UNKNOWN` | The builder image is out of date. Update the Toupas program and make the app live again. |
| `E_CHECKOUT_EXPIRED` | The payment link expired (30 minutes). Get a new one with toupas_get_checkout_link. |
| `E_CHECKOUT_INVALID` | That payment link can’t be used. Get a new one. |
| `E_CLI_OUTDATED` | This Toupas program is too old. Ask the user to update it: `curl -fsSL https://app.toupas.com/install.sh | sh` (Windows: `irm https://app.toupas.com/install.ps1 | iex`), then start a new agent session. |
| `E_CODE_EXPIRED` | The sign-in code expired. The user can ask for a new one. |
| `E_CODE_INVALID` | The sign-in code was wrong. The user can ask for a new one. |
| `E_CONFIG_INVALID` | toupas.json has a mistake; the message names it (toupas://docs/toupas-json). |
| `E_CONFIRM` | Nothing was done. Show the user what would happen and call again with confirm: true only if they agree. |
| `E_CONFIRMATION_REQUIRED` | Nothing was done. Show the user what would happen and call again with confirm: true only if they agree. |
| `E_CONFLICT` | It clashes with how things are now; the message says why. |
| `E_DATABASE_EXISTS` | The app already has a database. |
| `E_DATABASE_FAILED` | Creating the database failed. Try again; if it keeps failing, tell the user. |
| `E_DATABASE_MISSING` | The app has no database yet: toupas_create_database (toupas_make_live creates it when the app uses Postgres). |
| `E_DATABASE_NOT_READY` | The database is still being created. Wait a minute and try again. |
| `E_DATABASE_OWN_URL` | The app uses its own DATABASE_URL, so Toupas leaves the database alone. Unset it first to use Toupas’s. |
| `E_DATABASE_SLOW` | The database is taking longer than usual. Check again with toupas_get_database in a minute. |
| `E_DATABASES_NOT_CONFIGURED` | Databases aren’t available on this server yet. |
| `E_DB_ACCESS_OFF` | Direct access to the live database is off. An owner or admin turns it on in the panel (the link is in the error); then try again. |
| `E_DB_LOGIN_EXPIRED` | The temporary database login expired. Try again. |
| `E_DB_LOGIN_FAILED` | The temporary database login didn’t work. Try again. |
| `E_DEPENDENCY_MISSING` | The app needs a dependency to run live (e.g. uvicorn or gunicorn); the message names it. Add it to the dependencies and make the app live again. |
| `E_DEPLOYMENT_FAILED` | The new version didn’t go live; the previous one (if any) still is. Read the logs in the error (or toupas_get_logs), fix the cause, and make it live again. |
| `E_DEPLOYMENT_NOT_UPLOADING` | That version was already sent or replaced. Make the app live again. |
| `E_DEV_DB_START` | The local database didn’t start. Check Docker Desktop is running. |
| `E_DEV_STORAGE_PULL` | Docker couldn’t download the local storage. Check the internet connection and Docker Desktop. |
| `E_DEV_STORAGE_START` | The local storage didn’t start. Check Docker Desktop is running. |
| `E_DEVICE_CODE_EXPIRED` | The sign-in link expired. Call the tool again for a new one. |
| `E_DOCKER_EMULATION` | Docker runs Toupas’s builder through emulation here, which is slow but works. On Apple Silicon, turn on “Use Rosetta” in Docker Desktop’s settings to speed it up. |
| `E_DOCKER_MISSING` | Apps with their own server need Docker Desktop. Ask the user, as agentInstructions say, and if they agree call toupas_setup_docker. |
| `E_DOCKER_NOT_RUNNING` | Docker Desktop is installed but not running. Ask the user to open it (and click Accept the first time), then try again. |
| `E_DOCKER_RELOGIN` | Docker was just installed. The user logs out of the computer and back in, then try again. |
| `E_DOCKER_SETUP` | Installing Docker Desktop didn’t work; the message says why. The user can install it from docker.com. |
| `E_DOCKER_SETUP_CANCELLED` | The user cancelled the install. Ask whether they still want it. |
| `E_DOCKER_SETUP_FAILED` | Installing Docker Desktop failed. The user can install it from docker.com, then try again. |
| `E_DOCKER_SETUP_TERMINAL` | This step needs the user to type in a terminal. Ask them to run `toupas setup docker` themselves. |
| `E_DOMAIN_INVALID` | That isn’t a domain the app can use, e.g. shop.example.com. |
| `E_DOMAIN_TAKEN` | That domain is already connected to another app. |
| `E_DOMAINS_NOT_CONFIGURED` | Own domains aren’t available on this server yet. |
| `E_DOTENV_DATABASE_URL` | .env already has a DATABASE_URL that isn’t Toupas’s local database. Ask the user before replacing it. |
| `E_DOTENV_STORAGE` | .env already has S3 settings that aren’t Toupas’s local storage. Ask the user before replacing them. |
| `E_DUMP_INVALID` | The file isn’t a pg_dump custom-format file. Make it with `pg_dump --format=custom`. |
| `E_EMAIL_DISPOSABLE` | Throwaway email addresses can’t be used. Ask the user for their real address. |
| `E_EMAIL_INVALID` | The email address doesn’t look right. Ask the user to check it. |
| `E_ENTRYPOINT_MISSING` | The start command names a file that isn’t in the prepared app. Fix `start` in toupas.json. |
| `E_ENV_INVALID` | Setting names use letters, numbers and underscores, starting with a letter or underscore. |
| `E_ENV_LIMIT` | Too many settings, or a value is too long. |
| `E_ENV_RESERVED` | That name is set by Toupas (PORT, TOUPAS_*) and can’t be changed. |
| `E_EXTENSION_NOT_ALLOWED` | That Postgres extension isn’t offered; the message lists the ones that are. |
| `E_FORBIDDEN` | The user’s role in this account doesn’t allow it (07 §9.2). Tell the user; an owner or admin can do it. |
| `E_IMAGE_BUILD_FAILED` | Installing the Debian packages from toupas.json failed; the message says why (often a misspelt package). Fix systemPackages/buildPackages, then call toupas_make_live again. |
| `E_INTEGRITY` | A file changed while it was being sent. Make it live again. |
| `E_INTERNAL` | Something went wrong in Toupas. Try again; if it keeps happening, tell the user to write to hello@toupas.com. |
| `E_INVALID_REQUEST` | A value sent to Toupas was wrong; the message says which. Fix the argument and try again. |
| `E_INVITATION_EMAIL_MISMATCH` | The invitation is for a different email address. Sign in with the invited one. |
| `E_INVITATION_INVALID` | The invitation is used, revoked or expired. Ask for a new one. |
| `E_LAST_OWNER` | An account always keeps one owner. Make someone else owner first (in the panel). |
| `E_LIMIT_DOMAINS` | The app has as many domains as allowed. |
| `E_LIMIT_IMAGE_BUILDS` | The account built its daily maximum of images with new package lists. Try again tomorrow, or keep the package list as it was. |
| `E_LIMIT_MEMBERS` | The team has the most members allowed (25). |
| `E_LIMIT_OWNED_TEAMS` | The user owns as many teams as allowed (5). |
| `E_LIMIT_PENDING_INVITATIONS` | Too many invitations are waiting (20). Revoke some in the panel. |
| `E_LIMIT_PROJECTS` | The account has as many apps as allowed. |
| `E_LIMIT_PROJECTS_PER_DAY` | The account made 10 new apps today. Try again tomorrow, or update an existing app. |
| `E_LIMIT_TRIAL_PROJECTS` | Five apps can be on a free trial at once. Move one to a plan (toupas_activate_project) or stop one. |
| `E_LINK_UNKNOWN` | That link isn’t one of the app’s. toupas_get_links lists them. |
| `E_LOCAL_DATA_STORAGE` | The app keeps data in local files (SQLite, uploads), which a live app loses. Follow agentInstructions: switch to the Toupas database or storage, then make it live again. |
| `E_LOCAL_DUMP_FAILED` | Copying the local database failed; the message says why. Check the local database is running. |
| `E_MANIFEST_INVALID` | The files sent didn’t make a valid version; the message says why. |
| `E_NETWORK` | Toupas couldn’t be reached. Check the internet connection and try again. |
| `E_NOT_FOUND` | It doesn’t exist, or belongs to an account this sign-in can’t see. Check the name with toupas_list_projects. |
| `E_NOT_LINKED` | This folder isn’t a Toupas app yet. Call toupas_make_live with its `dir` to make it live, or pass `project` to work on an existing app. |
| `E_NOT_SUPPORTED_YET` | Toupas doesn’t do this yet. Tell the user; don’t look for a way around it. |
| `E_OUTPUT_MISSING` | The build didn’t create the folder that goes live. Check `build.output` in toupas.json. |
| `E_PACKAGE_INVALID` | A name in systemPackages or buildPackages (toupas.json) isn’t a Debian package that can be installed. Fix the name (https://packages.debian.org, Debian 13) or remove it, then call toupas_make_live again. |
| `E_PACKAGE_JSON` | package.json couldn’t be read. Fix the JSON. |
| `E_PATH_INVALID` | A file name can’t be used live (e.g. it leaves the folder). Rename it or exclude it. |
| `E_PAYMENT_INVALID` | The payment couldn’t be confirmed. The user can try again in the browser. |
| `E_PAYMENT_REQUIRED` | This needs a payment. Give the user the link in details.url to pay in their browser; never pay yourself. Call again after they say it’s paid. |
| `E_PERSONAL_ACCOUNT_NO_MEMBERS` | Personal accounts have no members. The user can create a team in the Toupas panel. |
| `E_PG_TOOLS_PULL` | Docker couldn’t download Postgres’s tools. Check the internet connection and Docker Desktop. |
| `E_PLAN_REQUIRED` | The account needs a plan (the App plan for apps with a server or database). Give the user the link in details.url. |
| `E_PLATFORM` | This computer’s system isn’t supported for preparing apps with a server. |
| `E_PLATFORM_CAPACITY` | Toupas’s server is full right now. New trial apps wait in a queue and go live on their own; tell the user they’ll get an email. |
| `E_PORT_IN_USE` | That port is taken on this computer. Pick another with `--port`. |
| `E_PROJECT_OTHER_ACCOUNT` | The folder belongs to an app in another Toupas account. The user signs in to that account (`toupas login`), or deletes the folder’s `.toupas` folder to make it a new app. |
| `E_PROJECT_STOPPED` | The app is stopped. toupas_get_project says why; toupas_start_project or a payment starts it. |
| `E_QUERY_FAILED` | Postgres refused the query; its message is included. Fix the SQL. |
| `E_QUOTA_RAM` | The account’s RAM is used up. The user stops an app, lowers memoryMb, or adds RAM through the link in details.url. |
| `E_QUOTA_STORAGE` | The account’s storage is used up. The user deletes data or adds storage through the link in details.url. |
| `E_RATE_LIMITED` | Too many requests. Wait a minute, then try again. |
| `E_REAUTH_REQUIRED` | Only for the admin panel: the operator signs in again in the browser. |
| `E_RESTORE_FAILED` | Copying data into the live database failed; the message says why. |
| `E_RUNTIME_RETIRED` | That runtime is no longer offered. Switch `runtime` in toupas.json to a supported one. |
| `E_RUNTIME_UNAVAILABLE` | Toupas can’t run this language yet. Tell the user to try again later. |
| `E_RUNTIME_UNKNOWN` | That runtime doesn’t exist. toupas_list_runtimes lists them. |
| `E_SECRETS_NOT_CONFIGURED` | Secrets aren’t set up on this server. Tell the user. |
| `E_SETTING_MANAGED` | Toupas manages that setting (the database or storage). Change the database or storage instead. |
| `E_SIGN_IN_REQUIRED` | Give the user the sign-in link to approve in their browser, then call the same tool again. |
| `E_SLUG_TAKEN` | That account name is taken. Choose another. |
| `E_START_UNKNOWN` | Toupas couldn’t tell how to start the app. Set `start` in toupas.json, e.g. `node server.js`. |
| `E_STATIC_NO_INDEX` | A static site needs an index.html in the folder that goes live. Check `build.output`. |
| `E_STORAGE_ACCESS_OFF` | Direct access to the live files is off. An owner or admin turns it on in the panel (the link is in the error); then try again. |
| `E_STORAGE_DELETE` | Deleting files failed. Try again. |
| `E_STORAGE_EXISTS` | The app already has file storage. |
| `E_STORAGE_FULL` | The account’s storage is full; apps become read-only after the grace period. The user deletes data or adds storage. |
| `E_STORAGE_MISSING` | The app has no file storage yet: toupas_create_storage (toupas_make_live creates it when the app uses an S3 client). |
| `E_STORAGE_NOT_CONFIGURED` | Toupas’s storage isn’t set up on this server. Tell the user to try again later. |
| `E_STORAGE_NOT_SET_UP` | File storage isn’t ready yet. Try again in a minute. |
| `E_STORAGE_OWN_SETTINGS` | The app uses its own S3 storage settings. Ask the user whether Toupas should look after storage instead. |
| `E_STORAGE_PATH_INVALID` | That file path can’t be used. Use a relative path without `..`. |
| `E_STORAGE_PUBLIC_OFF` | Public files are off for this app. Turn them on with `toupas storage public enable` if files should be viewable by anyone. |
| `E_STORAGE_READ_ONLY` | The account’s storage is over its allowance, so writes are refused until usage goes down or storage is added. |
| `E_STORAGE_STATIC_APP` | Static sites have no file storage; only apps with their own server do. |
| `E_SUBDOMAIN_INVALID` | Names use lowercase letters, numbers and single hyphens, 3–40 long. |
| `E_SUBDOMAIN_RESERVED` | That name is reserved. Choose another. |
| `E_SUBDOMAIN_UNAVAILABLE` | That name is taken. Offer the user the suggestions in details.suggestions. |
| `E_TOO_LARGE` | The app is over a size limit; the message says which. Exclude what isn’t needed (`exclude` in toupas.json). |
| `E_TUNNEL_LIMIT` | Too many database connections from computers are open. Close one. |
| `E_UNAUTHENTICATED` | The user isn’t signed in, or was signed out. Call the tool again: it returns a sign-in link to give the user. |
| `E_USAGE` | The command or arguments weren’t right; the message says how to use it. |
| `E_USER_DECISION_REQUIRED` | Ask the user the askUser question, in its own words, and call again with their answer as an argument. Never decide for them. |