Skip to content

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)

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.