Guides
Errors
The error types are the same in every language. Python and TypeScript use classes derived from
SandboxError. Go uses typed errors, matched with errors.As, and sentinels, matched with errors.Is. Rust has one
chainguard_sandbox::Error enum, matched by variant.
| Error | Python | TypeScript | Go | Rust | Raised when |
|---|---|---|---|---|---|
| Base class | SandboxError |
SandboxError |
— | Error (the enum) |
any of the below, and unexpected service errors |
| Command failed | CommandExitError |
CommandExitError |
*CommandExitError |
Error::CommandExit(result) |
exit code ≠ 0 (run, wait). Carries exit_code/exitCode/ExitCode, stdout, stderr |
| Time limit | TimeoutError |
TimeoutError |
*TimeoutError |
Error::Timeout { op, result, .. } |
a command’s timeout passed (.result = output so far), the sandbox didn’t start in time, or kill couldn’t confirm the sandbox is gone |
| Missing path | FileNotFoundError (a NotFoundError) |
FileNotFoundError |
*NotFoundError |
Error::NotFound { what, name } |
file, directory or cwd doesn’t exist |
| Missing sandbox | SandboxNotFoundError |
SandboxNotFoundError |
*NotFoundError (What: "sandbox") |
Error::NotFound (what: "sandbox") |
connect, get_info on a deleted sandbox |
| Missing background command | NotFoundError |
NotFoundError |
*NotFoundError (What: "command") |
Error::NotFound (what: "command") |
commands.connect(pid) with an unknown pid |
| Wrong kind of path | InvalidPathError |
InvalidPathError |
*InvalidPathError |
Error::InvalidPath |
reading a directory, listing a file, writing over a directory |
| Session limit | LimitReachedError |
LimitReachedError |
ErrLimitReached |
Error::LimitReached |
create while at the session limit (one sandbox per user and three per organization during the beta) |
| Workspaces is off | WorkspacesNotEnabledError |
WorkspacesNotEnabledError |
ErrNotEnabled |
Error::NotEnabled |
create in an organization where Workspaces isn’t turned on. See Enabling Workspaces |
| Terms not accepted | TermsNotAcceptedError (.missing) |
TermsNotAcceptedError (.missing) |
*TermsNotAcceptedError |
Error::TermsNotAccepted { missing } |
turning Workspaces on without agreeing to the documents it lists |
| GitHub App not installed | GitHubAppNotInstalledError (.install_url) |
GitHubAppNotInstalledError (.installUrl) |
*GitHubAppNotInstalledError |
Error::GitHubAppNotInstalled { install_url, .. } |
turning Workspaces on, when the Chainguard GitHub App isn’t on the GitHub account being linked |
| GitHub link needed | GitHubLinkRequiredError |
GitHubLinkRequiredError |
*GitHubLinkRequiredError |
Error::GitHubLinkRequired |
turning Workspaces on without a browser, for an organization with no GitHub account linked |
| Busy | SandboxBusyError |
SandboxBusyError |
ErrBusy |
Error::Busy |
an interactive shell is attached to the sandbox |
| Unknown outcome | OutcomeUnknownError |
OutcomeUnknownError |
ErrOutcomeUnknown |
Error::OutcomeUnknown |
the connection ended or failed before the command reported an exit status; it may have run. The transport error is kept (.cause; in Go, status.Code(err); in Rust, cause and grpc_code()) |
Python’s FileNotFoundError and TimeoutError live in chainguard_sandbox and are not the
builtins. Import them from the package, as E2B and Modal do with their own exception classes.
from chainguard_sandbox import CommandExitError, FileNotFoundError, SandboxError
try: sbx.commands.run("make test")except CommandExitError as e: print(e.exit_code, e.stderr)except SandboxError as e: print("sandbox problem:", e)import { CommandExitError, SandboxError } from "chainguard-sandbox-sdk";
try { await sbx.commands.run("make test");} catch (e) { if (e instanceof CommandExitError) console.log(e.exitCode, e.stderr); else if (e instanceof SandboxError) console.log("sandbox problem:", e.message); else throw e;}_, err := sb.Commands.Run(ctx, "make test", nil)var exit *sandbox.CommandExitErrorswitch {case errors.As(err, &exit): fmt.Println(exit.ExitCode, exit.Stderr)case errors.Is(err, sandbox.ErrBusy): fmt.Println("detach the interactive shell first")case err != nil: return err}use chainguard_sandbox::Error;
match sbx.commands.run("make test").await { Ok(r) => println!("{}", r.stdout), Err(Error::CommandExit(r)) => println!("tests failed: {}", r.stderr), Err(e) => println!("another error: {e}"),}If no organization can be determined (none set, and auto-detection found none or several), creating or connecting fails with a message that lists the three ways to set one and how to list your organization IDs. With several organizations the IDs and names are in the message. See Choosing the organization.
Authentication problems surface as the library’s own errors. For example LoginRequiredError /
ErrLoginRequired / Error::LoginRequired is raised when no login is saved and opening a browser is disabled. See
Authentication.
