Errors

Sailbox and image error taxonomy

All SDK failures share one taxonomy: catch the base SailError for everything, or match a specific failure.

Python

import sail

try:
    sb = sail.Sailbox.create(app=app, name="box")
    result = sb.exec("false", timeout=5).wait()
except sail.SailboxCreationError:
    ...  # creation failed
except sail.SailboxError:
    ...  # any other Sailbox failure

Command failure is not an exception

A command that runs to completion and exits nonzero is not an SDK failure. run and exec(...).wait() return normally with the exit code on the result. Check it yourself:

Python

result = sb.run("make test")
if result.exit_code != 0:
    print(result.stderr)

To treat command failure as an error, pass check to run: a nonzero exit or a timeout then raises CommandFailedError, which includes the completed result. Rust doesn’t have check. It reports a nonzero exit through the returned ExecResult, so use the exit-code check above.

Python

try:
    sb.run("make test", check=True)
except sail.CommandFailedError as err:
    print(err.result.stderr)

Exec errors in the taxonomy below cover the SDK failing to run the command at all, not the command’s own exit status.

The taxonomy

Failure	Python	TypeScript	Rust SailError::
Creation failed	SailboxCreationError	SailboxCreationError	Creation
Custom image build failed	ImageBuildError	ImageBuildError	ImageBuild
Exec failed	SailboxExecutionError	SailboxExecutionError	Execution
Sailbox gone (terminated)	SailboxTerminatedError	SailboxTerminatedError	Terminated
Unknown exec request	SailboxExecRequestNotFoundError	SailboxExecRequestNotFoundError	ExecRequestNotFound
Host machine lost mid-run	SailboxHostLostError	SailboxHostLostError	HostLost
Unknown id / unexposed port	NotFoundError	NotFoundError	NotFound
Auth failure	PermissionDeniedError	PermissionDeniedError	PermissionDenied
Invalid argument	InvalidArgumentError	InvalidArgumentError	InvalidArgument
Missing guest file	FileNotFoundError	FileNotFoundError	FileNotFound
Readiness or build timeout	TimeoutError	TimeoutError	Transport (timeout)
Writing to a closed stdin	BrokenPipeError	BrokenPipeError	BrokenPipe
Network/transport failure	TransportError	TransportError	Transport
Deleting an in-use secret	SecretInUseError	SecretInUseError	Api
Deleting an attached policy	EgressPolicyInUseError	EgressPolicyInUseError	Api
Unexpected API response	ApiError	ApiError	Api

Every class derives from sail.SailError. The Python classes that match a Python builtin also inherit it (NotFoundError is a LookupError, TimeoutError the builtin TimeoutError, ApiError a RuntimeError, and so on), so handlers written against the builtins keep working. SecretInUseError and EgressPolicyInUseError subclass ApiError, so handlers that catch ApiError also catch them. API and creation failures include status_code (status in TypeScript) and the parsed response body. Every error has a retryable flag. True means retrying the same call may succeed (the failure was transient, like a network drop or a busy service). False means it is deterministic and a retry would just fail the same way.

Notable errors

Creation failed

Raised when Sailbox.create fails. When creation succeeded but SSH setup failed (with ssh=True), the message includes the new Sailbox’s id so you can fetch it to retry enable_ssh or terminate it.

Host machine lost mid-run

The machine hosting your Sailbox failed before the command finished. The command may have run only partially, and its output is gone. The run cannot be resumed: calling exec again starts it over from the beginning, so any side effects the partial run applied will happen again. The Sailbox itself recovers automatically, and you do not need to resume it.

Function errors (Python only)

SailboxFunctionError is raised when a @sail.function call fails while running in the Sailbox. It includes the remote failure context:

Attribute	Type	Description
error_type	str	Remote exception class name.
traceback	str	Remote traceback text.
stdout	str	Captured remote stdout.
stderr	str	Captured remote stderr.

SailboxFunctionSerializationError is raised when a function payload or result cannot be serialized, or the remote function runtime cannot be prepared (including a Python major.minor version mismatch between your local interpreter and the Sailbox’s python3). Both are subclasses of SailboxExecutionError.