Errors

A tool that fails returns a normal result with isError: true, never a protocol error:

{
  "content": [{ "type": "text", "text": "error: <message>" }],
  "isError": true,
  "structuredContent": { "error": { "kind": "<kind>", "message": "<message>" } }
}

Branch on kind; the message is for people. Every tool can return invalid_argument. A tool that takes space can also return not_found and ambiguous_sandbox; one with spacesd requires, spacesd_not_available and capability_missing; one with host requirements, host_capability_missing. Each tool lists the rest.

Error kinds#

invalid_argument#

An argument is missing, malformed or out of range.

Fix: Check the call against the tool's input schema; the message names the argument.

Listed by volume_storage_set, volume_cache_set.

not_found#

No Space, run, window, service, tool or file with that id.

Fix: List what exists first (list_spaces, agent_list, list_space_windows, list_tools).

Listed by volume_sync_resolve.

spacesd_not_available#

The machine answered but runs no cua-spacesd, so the spacesd primitives cannot work.

Fix: Use an image that runs cua-spacesd (for example ghcr.io/trycua/linux:24.04), or reach the Space's own services with list_tools and call_tool.

capability_missing#

The Space's cua-spacesd reports a feature this tool needs as unsupported; the message names it and the driver's limitation.

Fix: Use a Space whose spacesd supports the feature (see the tool's requires).

host_capability_missing#

A prerequisite on this machine is missing: Fleet credentials, a local runtime, an operator display or app-session providers.

Fix: Set up what the message names (see the tool's host_requires).

wrong_provider#

The operation does not apply to this kind of Space.

Fix: Use a tool that serves the Space's provider (see the tool's providers).

Listed by stop_space, start_space.

unauthenticated#

The Space's spacesd or the cua.ai relay rejected the token.

Fix: Re-add the Space with a valid token, or sign in again with cua auth login.

Listed by add_space, list_spaces, share_space, unshare_space, space_shares, relay_register_space, relay_unregister_space.

permission_denied#

The signed-in account may not reach that relay machine.

Fix: Sign in with the account that owns the machine.

Listed by stop_space, start_space, share_space, unshare_space.

ambiguous_host#

The machine name given to on="host:<name>" fits several of your machines equally well; the message lists them.

Fix: Ask the user which machine they meant, then pass on="host:<machine id>" from the list.

Listed by create_space.

limit_exceeded#

The host is at a capacity limit: two macOS VMs per Mac (Apple's macOS license, enforced by Apple Virtualization) or the host's own Space limit.

Fix: Delete a Space on that host (delete_space), pick another machine, or create a Linux Space instead.

Listed by create_space.

ambiguous_sandbox#

A short name matches more than one sandbox.

Fix: Use the full id (local:<name> or cloud:<name>).

transfer_failed#

A file transfer did not land, or landed with a different sha256.

Fix: Retry; check free space and permissions at the destination.

Listed by space_write, upload, send_file, download, teleport_app.

teleport_refused#

The teleport consent gate refused: a sensitive item without acknowledge_sensitive, a declined approval, or a Space that cannot import the app.

Fix: Read teleport_manifest, then pass the items to move and acknowledge_sensitive=true for sensitive ones.

Listed by teleport_app.

login_refused#

The Keyvault refused a site login: the user declined, no saved password matches the page's origin, the tab is on another origin, or the Keyvault is locked or off.

Fix: Ask the user to approve the sign-in in Cua, import the site's saved password, or open the site's sign-in page and try again.

Listed by request_site_login.

agent#

An agent run failed outside the transport: install, configuration or a refused message.

Fix: Read agent_status and its output_tail for the reason.

Listed by agent_start, agent_message, agent_events, agent_status, agent_interrupt, agent_stop, agent_list, persistent_agent_create, persistent_agent_remove, persistent_agent_send, persistent_agent_save, agent_pause, agent_resume.

timeout#

A wait ran out: a claim that never bound, a Space that never became ready, or a command past its timeout.

Fix: Retry, or raise the tool's timeout.

Listed by create_space, start_space, space_bash.

cancelled#

The create was cancelled (cancel_create, or its caller went away); what it made is gone.

Fix: Nothing to clean up; create it again when you want it.

stream#

The media plane failed to open or run the stream.

Fix: Check that the Space's spacesd supports desktop_stream or window_stream, then retry.

Listed by stream_endpoint, stream_space_window.

env#

A cua-spacesd call failed.

Fix: Retry; if it persists, check the spacesd log in the Space.

fleet#

The Fleet control plane failed a cloud Space call.

Fix: See the Fleet errors reference for the HTTP status in the message.

Listed by create_space, delete_space, agent_resume.

fleet_admission_denied#

Fleet's admission refused the cloud Space: a size over this account's limits, or a template its policy does not admit. The message is Fleet's and names the limit.

Fix: Pick a size within the limit the message names (most accounts run 1-8 vCPUs and 1-32 GiB), or contact Cua support to raise the account's limits.

Listed by create_space.

cloud_credit_exhausted#

The account is out of Cua Cloud credit (no credit left, and no card or plan): Fleet refused the new cloud Space. Running Spaces keep running; local Spaces are never affected. The message ends with the billing page's URL.

Fix: Add credit on the billing page the message names (a plan, or a card for pay as you go), or create the Space locally.

Listed by create_space.

invalid_placement#

The location, kind or runtime does not exist, or the combination (with the image) does not.

Fix: Use one of the values the message lists, or leave kind and runtime unset (auto).

Listed by create_space.

sandbox#

Starting, stopping or deleting the Space's sandbox failed.

Fix: Check the local runtime (cua doctor) or the cloud pool, then retry.

Listed by create_space, delete_space, stop_space, start_space, agent_pause, agent_resume.

cloud#

Your cloud account refused or failed a call Cua made for a Space there (AWS, Google Cloud, Modal): a missing permission, a quota, a region without the instance type. The message names the cloud's own error.

Fix: Fix what the message names in that account (cua cloud test <provider> checks without creating anything), or connect another region or project.

Listed by stop_space, start_space, cloud_connect, cloud_test, cloud_sweep.

relay#

The cua.ai relay directory failed.

Fix: Retry; check cua auth status.

Listed by list_spaces, stop_space, start_space, share_space, unshare_space, space_shares, relay_register_space, relay_unregister_space.

mcp#

An MCP service inside the Space failed.

Fix: Check the service with list_tools; the message carries its error.

Listed by list_tools, call_tool.

io#

Reading or writing a local file failed.

Fix: Check the path and its permissions on this machine.

Listed by upload, send_file, download.

json#

A reply could not be parsed.

Fix: Retry; report it if it persists.

forbidden#

The drive's access rules refuse this principal on this path (an agent outside its own home, its Space's folder, read-only public/ and its grants).

Fix: Ask for access with volume_request_access; the user approves it in Cua.

Listed by volume_ls, volume_read, volume_write, volume_delete, volume_history, volume_restore, volume_grant, volume_revoke, volume_grants, volume_request_access, volume_requests, volume_approve, volume_deny, volume_audit, volume_storage, volume_storage_set, volume_mount_status, volume_mount, volume_unmount, volume_sync_status, volume_sync_events, volume_sync_resolve, volume_cache_stats, volume_cache_set, volume_cache_clear.

precondition_failed#

A drive write or delete with if_etag or create_only found a different version at the path.

Fix: Read the file again and retry with its current etag.

Listed by volume_write, volume_delete.

secret_detected#

A write under agents/ carries something that looks like a secret (an API key, a token, a private key); it was not stored. The message names the kind and line, never the value.

Fix: Remove the secret from the file; keep credentials in the Keyvault.

Listed by persistent_agent_save, volume_write, volume_restore.

lease_held#

Another run holds the persistent agent's home (one writer at a time).

Fix: Wait for that run to stop, or stop it; the lease expires on its own.

Listed by persistent_agent_send.

not_confirmed#

The user did not confirm with presence (Touch ID, the login password or the vault passphrase), so no access was widened.

Fix: Ask the user to approve it in Cua.

Listed by computer_access_grant, volume_grant, volume_approve.

volume_backend#

The drive's store failed or is not configured (a bucket that refused, missing keys, or a backend this build cannot serve).

Fix: Check cua volume config show and the message.

Listed by volume_ls, volume_read, volume_write, volume_delete, volume_history, volume_restore, volume_unmount.

Protocol errors#

JSON-RPC errors are about the message, not the tool.