Errors

Every error Basemodo can answer, by its code: what it means and what to do. Each error links here, to its own entry.

Every error, from the CLI, the MCP or the API, has the same shape:

{"error": {"code": "app_not_found", "message": "you have no App named lunch-rota", "fix": "basemodo deploy --name lunch-rota", "docs": "https://basemodo.com/docs/errors#app_not_found"}}

code is stable: programs and agents act on it.
message says what happened, for people.
fix, when there is one, is the exact command to run or basemodo.toml line to change. Try it first.
docs links to the entry below.

A failed Deploy adds deploy (its id) and, when the build failed, log (the build log). In a terminal without --json, the message, fix: and docs: are printed on stderr, and the CLI exits with a non-zero code.

Signing in

`not_signed_in`

You are not signed in, or your sign-in expired (after 30 days) or was revoked. Run basemodo login. An agent asks you to run it in a terminal.

`too_many_sign_in_links`

Five sign-in links were sent to this email in the last 15 minutes. Use the latest email, or wait a few minutes.

`email_not_sent`

Basemodo could not send an email (a sign-in link, an invitation). Nothing else changed; try again in a minute.

`magic_link_invalid`

The sign-in link is not one Basemodo sent. Open the link from the email as it is, without cutting it.

`magic_link_used`

Each sign-in link works once, and this one was used. Ask for a new one on the sign-in page.

`magic_link_expired`

Sign-in links work for 15 minutes. Ask for a new one on the sign-in page.

`invalid_email`

That is not an email address. Check for typos and spaces.

`invalid_return_to`

Where to go after signing in must be a page of Basemodo. Start the sign-in again from the page you wanted.

`sign_in_unavailable`

That way of signing in (Google or GitHub) is not available right now. Sign in with an email link instead.

`sign_in_cancelled`

The sign-in was cancelled at Google or GitHub. Start again when you are ready.

`sign_in_expired`

The sign-in took longer than 10 minutes, or was started in another browser. Start it again.

`email_not_verified`

Your Google or GitHub account has no verified email, so Basemodo cannot tell who you are. Verify the email there, or sign in with an email link.

`sign_in_failed`

Google or GitHub did not complete the sign-in. Try again, or sign in with an email link.

`app_sign_in_invalid`

Signing in to an App took too long, was already used, or was started in another browser. Open the App's address again.

`no_app_at_host`

No App answers at this address: the name is wrong, or it has nothing deployed yet. Check the address with basemodo status.

`access_denied`

The sign-in was refused in the browser. Run basemodo login again and approve it.

`sign_in_timed_out`

The sign-in was not approved in time. Run basemodo login again.

`local_server_failed`

basemodo login could not listen on this computer for the browser to come back. Use basemodo login --device, which needs no local port.

`invalid_api_url`

--api-url (or BASEMODO_API_URL) is not a URL. Use one like https://api.basemodo.com, or leave it out.

`authorization_pending`

The code shown by basemodo login --device is not approved yet. The CLI keeps waiting by itself; approve it at basemodo.com/device.

`cli_code_invalid`

The sign-in code the CLI used is not valid. Run basemodo login again.

`cli_code_used`

The sign-in code was already used; each works once. Run basemodo login again.

`cli_code_expired`

The sign-in code expired. Run basemodo login again.

`cli_sign_in_not_found`

No CLI is waiting for the code you entered. Check it against the code your terminal shows, or run basemodo login --device again.

`invalid_redirect_uri`

The CLI, or an agent connecting to the remote MCP, asked to be sent back somewhere it did not register (the CLI: anywhere but this computer), which Basemodo never allows. Update the CLI and run basemodo login, or connect the agent to Basemodo again.

`invalid_code_challenge`

The CLI's sign-in request is malformed. Update the CLI, then run basemodo login.

`invalid_device_name`

The CLI did not say which computer it runs on. Update the CLI, then run basemodo login.

`no_config_dir`

The CLI cannot tell where to keep its sign-in, because HOME is not set. Set BASEMODO_CONFIG_DIR to a folder.

`credentials_unreadable`

The CLI's credentials.json is damaged. Delete it (the message names it) and run basemodo login.

`credentials_unwritable`

The CLI cannot write its credentials.json. Check the folder it names exists and is yours, or set BASEMODO_CONFIG_DIR.

`invalid_client`

The agent that sent you to approve it is not one Basemodo knows: it never registered, or its client metadata document cannot be read or is not valid (the message says which). Connect the agent to Basemodo's MCP again; if it keeps failing, the agent's maker must fix its document. See Deploying with an agent.

`device_not_found`

That device is not signed in as you, or was already signed out. Reload the Devices page.

Apps and Deploys

`app_not_found`

You have no App by that name or id (or you may not deploy it). Check the name with --app; without it, the CLI uses the App named after the current folder. To create it, deploy: the fix names the command.

`app_exists`

You already have an App with that name. Deploy to it, or choose another name with --name.

`invalid_app_name`

App names are lowercase letters, digits and dashes, at most 40, starting and ending with a letter or digit. Choose one with --name, or name in basemodo.toml.

`no_folder`

The CLI cannot open the folder to deploy. Check the path, and that you may read it. The remote MCP has no folder at all: deploy a GitHub repository with repository instead.

`app_not_named`

The remote MCP has no folder to name the App after. Call the tool again with app set to the App's name.

`unreadable_folder`

A file of the folder cannot be read. Fix its permissions, or leave it out with a .basemodoignore line.

`invalid_source`

The upload is not a folder Basemodo accepts: a file outside it, a link, or too many files (more than 20,000). Leave the offending files out with .basemodoignore.

`source_too_large`

The folder packs to more than 50 MB (or 200 MB unpacked). Leave dependencies and build output out with a .basemodoignore file: Basemodo installs and builds them itself.

`source_not_found`

The upload this Deploy names is not the App's. Run basemodo deploy again.

`invalid_manifest`

basemodo.toml has a mistake: an unknown key, a wrong value, or invalid TOML. The message names the key and the line; the fix is the line to write. Every key is on the manifest's page.

`nothing_detected`

Basemodo does not recognize the folder, or recognizes it but cannot tell how to start it. The fix names what to add: a Dockerfile, an index.html, a start script, or [web] command in basemodo.toml. See Supported runtimes.

`deploy_not_found`

You have no Deploy with that id. Deploy ids are printed by basemodo deploy --json and listed on the App's page.

`deploy_never_live`

That Deploy never went live, so it cannot be brought back. Roll back to one that did.

`deploy_timeout`

The CLI stopped waiting, but the Deploy is still running on Basemodo. Check it with basemodo status.

`build_failed`

The build stopped with an error. The error carries the build log: read its last lines, fix the code or the build command, and deploy again. The previous version keeps running.

`builder_unavailable`

Basemodo's builders could not take the build. Nothing is wrong with your App; deploy again in a minute.

`start_failed`

The new version could not start on the App's machine. Deploy again; if it repeats, check the start command (web.command, or your Dockerfile's CMD).

`not_ready`

The new version started but never answered HTTP within 60 seconds. It must listen on the port in $PORT, on 0.0.0.0 (not localhost). See the Port Contract. The previous version keeps running.

`network_policy_unenforced`

The new version did not start because its Machine could not hold it to its network policy: Basemodo's supervisor, which installs the Machine's firewall and answers its DNS before anything runs, could not, and an App never runs without them. The App's Logs say why, in a line starting [basemodo] the network policy cannot be enforced. This is on Basemodo's side, not your code's; the previous version keeps running. Deploy again later.

`interrupted`

Basemodo restarted while this Deploy was building or starting. Deploy again.

`app_paused`

The App is paused, so it cannot be woken or run commands: one of its workers kept crashing (its Logs say which, and why), it ran out of its memory or disk quota, its Owner's Trial ended, or Basemodo paused it for review (see Abuse and limits). basemodo status gives the reason and what resumes it: fix the cause and deploy again (or basemodo restart), after a Trial choose a Plan, and after a review wait for Basemodo's answer.

GitHub

`github_unavailable`

Linking GitHub repositories is not set up on this Basemodo. Deploy from a folder with basemodo deploy instead.

`github_not_linked`

The App is not linked to a GitHub repository. Link it from a clone of the repository with basemodo deploy --link, or from the App's page. See Deploying from GitHub.

`github_disconnected`

Basemodo's GitHub App can no longer read the repository the App is linked to (the installation was removed or suspended, or the repository taken from it). Give it access again with the link in the fix; the link resumes as it was.

`source_unavailable`

Basemodo could not fetch the commit from GitHub: the branch may not exist, or GitHub did not answer. Check the branch, then deploy (or push) again in a moment.

`repository_not_covered`

Basemodo's GitHub App cannot read that repository: install it on the repository's owner, or give your installation access to that repository. The fix is the install link.

`invalid_repository`

Name a repository as owner/repo, as in acme/lunch-rota.

`invalid_branch`

That is not a branch name. Leave it out to use the repository's default branch.

`invalid_subdir`

The folder of the repository is written like apps/web: no leading or trailing /, no ...

`invalid_signature`

A delivery to one of Basemodo's webhooks is not signed as it should be, so it is ignored: to the GitHub webhook, with the GitHub App's secret; to the billing webhook, by the payment provider (recently, with the endpoint's secret). Only GitHub and the payment provider send these.

`invalid_delivery`

A delivery to Basemodo's GitHub webhook lacks its event or its id. Only GitHub sends these.

`invalid_visibility`

A Visibility is private, workspace, link or public. See Sharing.

`visibility_not_available`

Workspace Visibility is only for Apps a Workspace owns, and this App is a person's. Move it into your Workspace from its page on basemodo.com (an Admin accepts), or share it with link or by inviting people.

`app_not_public`

Only a Public App can be indexed by search engines. Make it Public first with basemodo share --visibility public, then basemodo indexing on.

`no_emails`

Name at least one email to invite.

`already_owner`

That person owns the App already; they need no invitation.

`too_many_invitations`

You sent the most invitations allowed in a day (100). Try again tomorrow, or open the App to anyone with its link: basemodo share --visibility link.

`owner_only`

You are an Editor of this App: you may deploy it, read its Logs, change its Secrets and take Backups, but only its Owner changes who can reach it, restores a Backup, downloads its data or deletes it. Ask the Owner. See Roles.

`invalid_role`

People are invited as a Member (basemodo share EMAIL) or an Editor (basemodo share --editor EMAIL); an App has one Owner.

`already_has_access`

You can already open this App: no need to ask. Open its address.

`too_many_access_requests`

You asked for access to the most Apps allowed in a day. Try again tomorrow, or ask the Owner directly.

`access_request_not_found`

That email has no pending Access Request to this App: it was already answered, or never made. See who asked with basemodo share.

`member_not_found`

That email is not a Member of the App nor invited to it. See who is with basemodo share.

Workspaces and Transfers

`ambiguous_app`

You have an App of that name and so does a Workspace of yours (or two Workspaces do). Name the Workspace with --workspace, or the App by its slug, the label in its URL: the fix gives both.

`workspace_not_found`

You are not in a Workspace by that name or id. See your Workspaces on basemodo.com.

`invalid_workspace_name`

A Workspace's name is 1 to a few dozen characters, like Acme.

`not_an_admin`

Only an Admin of the Workspace can do that: create its Apps, manage its people, its domains and its Apps' sharing. Ask an Admin. See Roles.

`invitation_not_found`

You have no invitation to that Workspace. Ask an Admin of the Workspace to invite your email.

`person_not_found`

That person is not in the Workspace.

`last_admin`

A Workspace always has an Admin. Make someone else an Admin before removing this one or making them a Member.

`invalid_domain`

Name your company's domain, like acme.com; for a custom domain, a hostname of yours like app.example.com, not one of Basemodo's own.

`domain_taken`

Another Workspace already verified that domain, or another App already answers at that custom domain. Remove it there first.

`domain_not_found`

The Workspace (or the App) has not claimed that domain. Add it first, then verify it.

`domain_not_verified`

The domain's DNS records are not there yet: the message names the one missing (the TXT with your value, or for a custom domain the CNAME to Basemodo). Add it at your DNS provider; DNS changes can take a few minutes to show, then verify again.

`dns_unavailable`

Basemodo could not ask the DNS just now. Verify again in a minute.

`not_a_personal_app`

Only an App you own yourself can be moved into a Workspace or given to someone; this one belongs to someone else, or to a Workspace already.

`invalid_transfer`

Say where the App goes: a Workspace, or another Person by email, not both and not yourself.

`transfer_not_yours`

Only the Person an App is offered to accepts or declines it. Wait for their answer, or cancel the Transfer.

`transfer_pending`

The App already waits for an answer to a Transfer. Cancel it to ask again.

`transfer_not_found`

You have no Transfer by that id to answer. Reload the page.

`transfer_not_pending`

The Transfer was already accepted, refused or cancelled (or the App changed hands meanwhile), so it cannot be answered.

Secrets

`invalid_secret`

Write each Secret as NAME=value, or one NAME alone with its value on stdin.

`invalid_secret_name`

A Secret's name is letters, digits and _, not starting with a digit, at most 128 characters.

`reserved_secret_name`

PORT and names starting with BASEMODO_ are set by Basemodo for every App. Choose another name.

`secret_too_large`

A Secret's value is at most 32 KB. Keep larger data in a file on the App's disk.

`invalid_secret_value`

The value contains a NUL byte, which no environment variable can hold.

`no_secrets`

Name at least one Secret to set.

`too_many_secrets`

An App has at most 100 Secrets. Unset some first, or combine related values into one.

`secret_not_found`

The App has no Secret by that name. See them with basemodo env list.

Logs

`invalid_lines`

--lines is between 1 and 1000.

`invalid_cursor`

--after takes the cursor of an earlier basemodo logs --json answer, as it was given.

`invalid_query`

The request to read Logs has a parameter that is not a number or not a known one. Use the options of basemodo logs.

Run and db

`app_not_deployed`

The App has no machine yet, so there is nowhere to run the command, nothing to back up and nothing to restart. Deploy it first.

`invalid_command`

Give a command to run, as in basemodo run "npm run migrate".

`invalid_timeout`

--timeout is between 1 and 900 seconds.

`run_failed`

Basemodo could not run the command in the App's machine, and nothing ran. Try again; check basemodo status.

`run_lost`

Basemodo lost track of the command before it ended. It may have run, partly or fully: check its effects before running it again.

`wake_failed`

The App was asleep and its machine did not start. Try again in a minute; check basemodo logs.

`invalid_sql`

There is no SQL to run. Give it as an argument or on stdin.

`sql_error`

SQLite refused the SQL; the message is SQLite's own. Statements before the failing one did run.

`sqlite_missing`

The App's image has no sqlite3 program, so basemodo db cannot run SQL there (nor back up the database for the download of its data). Images Basemodo builds always have it; with your own Dockerfile, add the line the fix gives.

`db_timed_out`

The SQL ran longer than 60 seconds and was stopped. Make the query smaller, or run it in pieces.

`db_lost`

Basemodo lost track of the query before it ended. It may have run: check before running it again.

`db_unreadable`

The App's sqlite3 answered something Basemodo cannot read. Try a simpler query, or use basemodo run "sqlite3 /data/app.db '...'".

Backups and deleting an App

`backup_failed`

Basemodo could not take a Backup of the App's data just now; nothing changed. Try again in a moment.

`backup_not_found`

You have no Backup by that id, or it has expired: each is kept for its App's retention (7 days, 30 on Pro and Workspace). List the App's Backups with basemodo backups and restore one of those.

`backup_gone`

The Backup is still listed but its copy is no longer there to restore. Restore a newer one: basemodo backups.

`restore_failed`

Basemodo could not restore the Backup, and the App's data is as it was. Try again in a moment.

`archive_failed`

Basemodo could not make the archive of the App's data to download. Try again in a moment; check basemodo status.

`deploy_in_progress`

The App is being deployed, so it cannot be deleted right now. Wait for the Deploy to end (basemodo status), then delete it.

`delete_failed`

Basemodo could not stop the App, so it was not deleted. Try again in a moment.

Plans and quotas

`app_quota_reached`

Your Plan has no room for another App: the Trial and Starter allow one, Pro and Workspace more. The message lists the Apps you have. Deploy to one of them, delete one you no longer need (a deleted App frees its place), or choose a bigger Plan on the billing page the fix links to.

`trial_ended`

Your seven-day Trial ended without a Plan, so your Apps are paused and nothing new is created, deployed or restored. Their data is kept for 30 days (the message says until when). Choose a Plan on the billing page the fix links to: your Apps resume where they were.

`plan_ended`

The payment provider ended your Plan (it could not charge your card after retrying, or the subscription was cancelled), so your Apps are paused and nothing new is created, deployed or restored. Their data is kept for 30 days (the message says until when). Choose a Plan on the billing page the fix links to (update your card there first if it was declined): your Apps resume where they were.

`workers_not_on_plan`

basemodo.toml declares a [[worker]], and a worker keeps an App always on, which the Trial and Starter do not allow. Remove the [[worker]] (a cron job runs on every Plan), or move to Pro or Workspace.

`always_on_quota_reached`

A worker keeps an App always on, and your Plan's always-on Apps are all taken: the message names them. Remove a [[worker]] here or in another App, or choose a bigger Plan.

`plan_too_small`

The Plan you chose does not fit what you have: more Apps, always-on Apps or custom domains than it allows. The message says which. Delete Apps, remove workers or custom domains first, or choose a bigger Plan.

`custom_domains_not_on_plan`

Custom domains are on the Pro and Workspace Plans; the message names yours (the Trial, or Starter). Choose Pro on the billing page the fix links to, then add the domain again.

`custom_domain_quota_reached`

Your Apps already have as many custom domains as your Plan allows: the message lists them. Remove one you no longer use (basemodo domains remove), or choose a bigger Plan.

`plan_not_available`

The Workspace Plan is for a Workspace, not a person, and a Workspace pays only for the Workspace Plan. Choose Starter or Pro for yourself, or create a Workspace for your team.

`workspace_plan_needed`

A Workspace has no Trial: it creates Apps, and takes them in by Transfer, once an Admin has chosen the Workspace Plan, paid per seat. An Admin chooses it on the Workspace's page on basemodo.com (the fix links to it), then try again.

`billing_failed`

The payment provider did not answer, or did not take the change, so nothing changed. Try again in a moment.

`card_declined`

Your card was declined when Basemodo charged the difference for the Plan you chose, so nothing changed: you are still on your Plan. Change your card on the billing page the fix links to, then choose the Plan again.

Abuse and limits

`app_under_review`

Basemodo paused this App because something in its traffic looked like abuse, and a person at Basemodo is reviewing it: basemodo status says why. Nothing deploys, rolls back, restores or deletes it meanwhile. If nothing is wrong, Basemodo resumes it and you are told; if you think it is a mistake, write to abuse@basemodo.com. A Deploy already on its way when the App was paused fails with this code too.

`account_suspended`

Your account (or this Workspace) is suspended while Basemodo reviews it: its Apps are paused, and nothing new is created or deployed, by you or by you as an Editor of someone else's App. The message says why. Basemodo restores the account if nothing is wrong; write to abuse@basemodo.com if you think it is a mistake.

`source_flagged`

The files you deployed are the same as an App Basemodo stopped for abuse, so this Deploy was refused and the App is held for review. If the files are yours and harmless, write to abuse@basemodo.com.

`dedicated_ip_not_on_plan`

A dedicated egress IP (an outgoing address of the App's own, to allowlist in a firewall) is a paid extra of the Workspace plan, and this App is a personal one (or its Owner pays for no Plan yet). Move it into a Workspace first.

`on_probation`

A new account (the Trial, and the first 14 days of a paid account or a Workspace) is on probation: lower egress caps and no dedicated egress IP. The message says when it ends; ask again then.

`dedicated_ip_unavailable`

The compute provider this App runs on cannot give it an outgoing address of its own, so nothing changed: the App keeps leaving from the shared pool.

`egress_unavailable`

Basemodo could not change where the App's traffic leaves from. Nothing changed; try again in a moment.

`invalid_usage_report`

For Basemodo's own sensors: a usage report must cover one App over a window of at most an hour, to after from.

`not_an_operator`

Only Basemodo's operators may work the abuse review queue or suspend and restore accounts.

`review_not_found`

For operators: there is no review with that id. List the queue with GET /api/operator/reviews.

`review_decided`

For operators: that review was already cleared or upheld; the message says which.

`not_under_review`

For operators: the App has no open review to clear.

`owner_not_found`

For operators: there is no Person (by id or email) or Workspace by that id.

`already_suspended`

For operators: that account is already suspended.

`not_suspended`

For operators: that account is not suspended, so there is nothing to restore.

`invalid_reason`

For operators: say why. The Owner is told the reason.

`invalid_region`

For operators: a region is letters, digits and dashes (gra, iad).

`hosts_not_in_use`

For operators: this control plane runs Machines in memory, not on our own Hosts (BASEMODO_HOSTS=on).

`invalid_host`

For operators: a Host needs a name like gra-1, its region, a token of at least 32 characters and, over https://, its certificate's SHA-256 (basemodo-host fingerprint). It must be at an address of Basemodo's Host networks (BASEMODO_HOST_NETWORKS), and plain http:// only on the control plane's own computer.

`host_unreachable`

For operators: the agent did not answer with that token and certificate. Check BASEMODO_HOST_TOKEN and basemodo-host fingerprint on the Host, and that the control plane reaches it.

`host_exists`

For operators: there is already a Host by that name.

`host_not_found`

For operators: there is no Host by that name. List them with GET /api/operator/hosts.

`host_not_checked`

For operators: the Runner's contract has not passed against this Host, so it takes no Machine yet. See its last run on the Operator page, fix the Host, then run it again (POST /api/operator/hosts/{name}/check).

`host_checking`

For operators: the contract is running against this Host already. Its result shows on the Operator page.

`host_not_empty`

For operators: the Host still keeps Machines, or did not say what it keeps. Drain it, move its Apps, then remove it.

Notifications

`notification_not_found`

You have no notification with that id. Reload the notifications page.

Agents and the CLI itself

`invalid_arguments`

A tool was called with an argument it does not take, or a value of the wrong kind. The tool's input schema lists its arguments; they are the command's, named as on its page in the CLI.

`not_a_tool`

mcp serves the other commands; it cannot be called as one of them.

`cancelled`

The agent cancelled the call before it ended. What the command had done stays done.

`mcp`

The local MCP could not start or stopped. Check that the agent runs basemodo mcp as a stdio server.

`unknown_docs_topic`

basemodo docs has no page about that topic. List the pages with basemodo docs --list.

`docs_export_failed`

basemodo docs --export could not write the docs into the folder it was given. It builds basemodo.com/docs; pass it a folder you can write to.

`output`

The CLI could not write its result as JSON. Report it: this is a bug.

`unreachable`

Basemodo can't be reached right now: it did not answer, or what stands in front of it answered 502, 503 or 504 in its place. Try again in a minute. If it keeps happening, check your connection, and --api-url or BASEMODO_API_URL if you set one.

`unexpected_response`

Basemodo answered something the CLI cannot read, usually because the CLI is older than the API. Update the CLI.

Basemodo itself

`internal`

Something went wrong on Basemodo's side, not yours. Try again; if it repeats, tell us.

`database_unavailable`

Basemodo cannot reach its own database right now. Try again in a minute.

`not_the_gate`

Only Basemodo's own gate may ask where Apps answer.

`not_found`

There is no such API endpoint. The CLI may be older than the API: update it.

`invalid_body`

A request to the API had a body it could not read. Use the CLI, or send the JSON the endpoint expects.

`invalid_path`

An id in the request's address is not valid. Check the id you passed.