Errors
SandboxError, its codes, and when each one happens. A non-zero exit code is never an error.
The SDK throws only when the sandbox, the provider, or the request fails. A command that exits non-zero, times out, or is aborted resolves normally with ok: false. When the SDK does throw, it always throws SandboxError.
import { createSandbox, SandboxError } from "@opencoredev/sandbox-sdk";
import { e2b } from "@opencoredev/sandbox-sdk/e2b";
try {
await using box = await createSandbox(e2b(), { network: "none" });
await box.files.edit("app/index.ts", { find: "foo()", replace: "bar()" });
} catch (error) {
if (!(error instanceof SandboxError)) throw error;
if (error.retryable) {
console.warn("try again:", error.message);
} else {
console.error(error.code, error.message, error.hint);
}
}
Fields
| Field | Type | Meaning |
|---|---|---|
code |
see below | What kind of failure |
message |
string |
“What happened. Why. What to do next.” |
retryable |
boolean |
Whether the same call can succeed if you retry it |
hint |
string |
The next step on its own, for UIs |
provider |
string |
Provider name |
sandboxId |
string | undefined |
The sandbox involved, when there is one |
cause |
unknown |
A redacted string from the underlying failure, when there is one. See Causes. |
Secrets are redacted from message, cause, and logs. The same scrub runs on the SDK’s own messages, including the log tail in process_exited and readiness timeouts, so a URL in that tail shows as [URL REDACTED].
Causes
cause says where a failure came from without attaching the provider’s error object, which can hold credentials.
- A failure the adapter doesn’t recognize and that has no HTTP status, such as a
TypeErrorthrown inside the provider’s SDK or a refused connection, keeps its name and message, plus up to two nested causes. The message repeats it, for exampleVercel request failed: TypeError: fetch failed.These failures are usually bugs or network trouble, and the text is the only clue. - A recognized error keeps its name, such as
RateLimitError. - An HTTP or gRPC failure keeps its name and status, such as
Error HTTP 503. Response text never appears, because it can echo the request. - Daytona, Freestyle, and Tenki use a JSON object of bounded request fields instead (status, request ID, operation), with a
nativefield for an unrecognized failure.
Kept text is scrubbed before it reaches you: URLs, Authorization headers, bearer tokens, key=value pairs that look like credentials, the provider’s API key, and every secret registered with the sandbox become [REDACTED].
Codes
code is one of these fifteen strings, exported as the ErrorCode type.
| Code | When | What to do |
|---|---|---|
auth |
Missing or rejected credentials | Check the provider’s environment variables or factory options. On Vercel, a token also needs team and project IDs. |
not_found |
The sandbox ID doesn’t exist, for example in connectSandbox or after a Local deadline passed |
Create a new sandbox. With a key, createSandbox does this for you. |
quota |
The provider’s limits or billing stopped the request | Wait, reap unused sandboxes, or raise your plan. Usually retryable. |
unavailable |
The provider is down or unreachable | Retry with backoff. Usually retryable. |
unsupported |
The provider can’t do what you asked, such as a size or network policy | Change the option or the provider. The message says what the provider allows. See Capabilities. |
timeout |
A provider operation took too long, or a process’s readiness check timed out | For readiness, raise readyTimeoutMs and read the log tail in the message. The process keeps running. |
aborted |
Your signal fired |
Nothing, unless you want to retry with a fresh signal. A sandbox that arrived late was destroyed. |
outcome_unknown |
The request may or may not have happened, for example a create or a kill that lost its connection | Check the sandbox’s state before retrying. If in doubt, destroy it. |
process_exited |
A process exited before it was ready | Read the exit code and the last 50 log lines in the message, fix the command, and start it again. |
port_not_ready |
A preview’s waitMs ran out before the URL answered with a 2xx |
Check that the server listens on 0.0.0.0 and the right port, then read its logs. |
edit_not_found |
files.edit found no match |
Read the file again and use text that is in it. |
edit_not_unique |
files.edit found more than one match. The message lists their line numbers. |
Add surrounding lines to find so it matches once. |
file_not_found |
The path doesn’t exist | Check the path. Relative paths resolve against /workspace. |
invalid_argument |
The request itself is invalid, such as a bad port, a non-positive timeout, or an invalid environment variable name | Fix the input. Retrying won’t help. |
provider |
Any other provider failure, or an adapter that declares a capability without its method | Read message and cause. Report it if it looks like an SDK bug. |
Retrying
Check error.retryable, not the code. Each adapter sets it: quota and unavailable are usually retryable, and so is a provider timeout on E2B and Daytona. Everything else defaults to false.
import { createSandbox, SandboxError } from "@opencoredev/sandbox-sdk";
import { e2b } from "@opencoredev/sandbox-sdk/e2b";
async function createWithRetry(attempts = 3) {
for (let attempt = 1; ; attempt++) {
try {
return await createSandbox(e2b(), { key: "user:123" });
} catch (error) {
if (!(error instanceof SandboxError) || !error.retryable || attempt >= attempts) throw error;
await new Promise((resolve) => setTimeout(resolve, 1_000 * 2 ** attempt));
}
}
}
await using box = await createWithRetry();
With a key, retrying createSandbox is safe: if the first attempt did create a sandbox, the retry finds it.
In agent tools
When a tool call fails with SandboxError, the model gets the same message plus code, retryable, and a Next: line with the hint, so it can decide whether to try again.