Errors
This page helps you find out what an error means and what to do next. Look it up by the failure reason a program receives, or by the symptom you see. The linked pages explain each case in full.
Failure reasons
Most API errors carry an ErrorDetail, and its reason is the first field to check. When retryable is true, trying again may succeed: with a new command ID if the details have command_settled, otherwise with the same one. An error with no ErrorDetail has only its Connect code and message. See Error format.
reason | Meaning | What to do |
|---|---|---|
INVALID_REQUEST | The request is malformed or breaks a limit | Fix the request. See Defaults and limits |
NOT_FOUND | The object or path does not exist | Check the ID or path. A deleted Workspace can still be read by ID |
CONFLICT | The object's state or revision does not allow this request, or the command ID was used with different input | Read the object again and decide from its current state. See Expected revisions |
RESOURCE_EXHAUSTED | No node has room, or a limit such as disk space or stream count was reached | Check retryable. Retry later for capacity. Otherwise free the resource or reduce the request |
CAPABILITY_UNAVAILABLE | The guest, the node, or the deployment lacks what this needs, such as a newer guest or a configured metrics store | Read message. For an older guest, restart the Workspace. Otherwise ask the deployer |
UNSUPPORTED | The operation does not apply here, such as resizing a process with no terminal, or the other side lacks it | Read message. For a missing feature, see Querying capabilities first |
UNAUTHENTICATED | The identity or credential was not accepted | Check that the certificate has not expired. See Authentication |
PERMISSION_DENIED | The caller may not do this, or the guest refused the file or process operation | Check the identity, the credential's scopes, and the guest user |
SESSION_EXPIRED | The session credential expired | Request a new credential with a new command ID. The Go SDK does this for you. See Caching and renewing the credential |
SESSION_REVOKED | The credential was revoked, or the Workspace stopped or was deleted | Check the Workspace's state, then request a new credential |
UNAVAILABLE | A dependency is unavailable, the command is still running, or the Workspace's execution ended | When retryable is true, send the request again: with a new command ID if the details have command_settled, otherwise with the same one. When it is false, read the Workspace's state |
TIMED_OUT | The operation did not finish in time | Read the object's state and the command's result before you retry |
CANCELLED | Another command replaced this one, such as a force stop or a delete, or the request was cancelled | Read the object's state, and send the request again if you still need it |
PROTOCOL_INCOMPATIBLE | A node or guest gave an answer that breaks the contract | Report it to the deployer with the command ID. Mismatched versions are one possible cause; see Reinstall and upgrade |
VOLUME_LOST | The Volume bound to the Workspace is LOST. This is not retryable | Bind another Volume or delete the Workspace. See Guarantees and limits |
INTERNAL | An unexpected server error | Retry if retryable is true. Otherwise report it to the deployer with the command ID |
Workspace states
| State | What to do |
|---|---|
FAILED | Force stop, then start. See Recovering from FAILED |
UNKNOWN | Wait for the system to confirm the result, or resend the original command ID. See Operations by state |
AVAILABLE, but requests time out | The guest may be stuck. See Responsiveness of the guest |
Common symptoms
| Symptom | Likely cause | Details |
|---|---|---|
spec.template and spec.resources are required | A native API create without Resources. Only kibo fills in defaults | Creating a Workspace |
exactly one valid pipe or PTY mode is required | A native API Start without Mode | Commands and terminals |
managed identity directory … must not grant group or other access | The identity directory is readable by others | Connect to ctrl |
Could not resolve host, or bad address in the guest | Workspaces have no network access by default | Networking overview |
| A connection fails at once, or an Egress or Resolver fault | The network policy or your proxy or DNS upstream | Network troubleshooting |
Requests as the default user fail with CONFLICT, while root works | The Template's user was removed in the guest | Default user unavailable |
| Processes barely make progress | The Workspace is out of memory | Resources and health |
A file write returns 413 or resource_exhausted | The file is over 1 GiB, or the disk is full | Files |
kibo exits with a code of its own | See the table of categories | kibo exit codes |
E2B SDK errors
| What you see | Meaning | Details |
|---|---|---|
501, or SandboxError: 501: unimplemented: … | The gateway does not provide this capability. The message names it | Not supported |
| 404 for a sandbox you know exists | The gateway does not implement this endpoint | How unsupported calls fail |
404 template catalog record not found | The deployment has no Template with this name | Migrate from E2B |
502 on create or connect | The sandbox was not running within 90 seconds and may still start, or the call failed in Kibotos. Retry with the same Idempotency-Key | Creating a sandbox |
| 502 from queries and pause | The sandbox failed | Unplanned pauses, restarts, and failures |
503 with resource_exhausted | No node has room | Insufficient capacity |
409 from connect | The sandbox failed and cannot be started as it is | Resuming |
fetch failed | The certificate is not trusted, or the domain does not reach the gateway | Quickstart |
CommandExitError | The command exited with a non-zero code | Commands and terminals |
Troubleshooting by topic
- Networking
- Resources and health
- Commands and terminals
- Lifecycle
- Identity and enrollment
- Build your own Template
- Try Kibotos on a single machine
- Node and VMM processes
Next steps
- Write operations and errors: the rules for command IDs, revisions, and retries.
- Agent platform integration: how a platform reacts to failures.
- FailureReason: the enum in the API reference.
Defaults and limits
This page lists the defaults and limits a caller meets, with the page that explains each one. In the tables, Fixed means a deployment cannot change the value, and Deployer means the deployer can.
Identity, configuration, and connections
This page describes the identity, certificate, and configuration rules that ctrl, nodes, and clients share. It answers questions such as "what does this configuration item mean" and "where does this certificate come from, and when does it expire".