Skip to main content
All Sailbox and image exceptions derive from sail.SailError, the base for every SDK error. You can catch any sailbox failure with except sail.SailboxError, or everything the SDK raises with except sail.SailError. 
SailError
└─ SailboxError
   ├─ SailboxCreationError
   ├─ ImageBuildError
   └─ SailboxExecutionError
      ├─ SailboxTerminatedError
      ├─ SailboxExecRequestNotFoundError
      ├─ SailboxWorkerLostError
      ├─ SailboxExecInterruptedError
      ├─ SailboxFunctionError
      └─ SailboxFunctionSerializationError

import sail

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

​
SailError

Base class for all Sail SDK errors.

​
SailboxError

Base class for sailbox-specific errors. Subclass of SailError.

​
SailboxCreationError

Raised when Sailbox.create fails, including when an SSH-enabled box is created but the post-create sshd setup fails (the message includes the sailbox_id so you can reconnect or terminate it).

​
ImageBuildError

Raised when a custom image build fails or a local-file upload returns an unexpected outcome.

​
SailboxExecutionError

Base class for exec-related errors. Also raised directly when you try to exec on a paused sailbox.

​
SailboxTerminatedError

Raised when a sailbox no longer exists on the worker (the exec target is gone, likely because the sailbox is no longer running). Subclass of SailboxExecutionError.

​
SailboxExecRequestNotFoundError

Raised when a wait references an unknown exec request. Subclass of SailboxExecutionError.

​
SailboxWorkerLostError

Raised when the machine hosting the sailbox became unreachable and recovery is required. Call resume() and retry. Subclass of SailboxExecutionError.

​
SailboxExecInterruptedError

Raised when an exec was interrupted before completion and its output could not be recovered (for example, the worker proxy that owned the run was lost, or a worker migration outran the reattach window), so the result is indeterminate rather than a real exit. Relaunch the exec to retry. exec adds an idempotency key by default, so a fresh call is safe. Subclass of SailboxExecutionError.

​
SailboxFunctionError

Raised when a @sail.function call fails while running in the sailbox. Subclass of SailboxExecutionError. Carries the remote failure context:
AttributeTypeDescription
error_typestrRemote exception class name.
tracebackstrRemote traceback text.
stdoutstrCaptured remote stdout.
stderrstrCaptured remote stderr.

​
SailboxFunctionSerializationError

Raised when a Python 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). Subclass of SailboxExecutionError.
Some sailbox calls raise Python builtins where that is the most natural fit: LookupError for unknown ids and unexposed listener ports, PermissionError for auth failures, ValueError for invalid arguments, FileNotFoundError for missing files, and TimeoutError for readiness/build timeouts.