Skip to content

Errors

Stage-attributed error taxonomy for the code_interpreter SDLC.

A single, shared exception hierarchy for sandbox and template creation/execution failures. Every error carries the failing stage (stamped at the raise site, not an outer catch) and exposes transient — derived solely from #5418's BaseSandbox._is_transient_create_error so retry logic and user-facing surfacing never drift.

Every error is a gllm-core BaseError with a GL-SBX-* code. The sandbox layer moves to gl-sandbox later, so its codes already carry gl-sandbox's prefix; a code never changes once released.

BaseSandboxError(message=None, *, debug_info=None, recovery=None, original_error=None)

Bases: BaseError

Root of the GL-SBX-* errors raised by the sandbox layer (code_sandbox, code_template).

CodeInterpreterError(message=None, *, stage, classifier=None, original_error=None)

Bases: BaseSandboxError, RuntimeError

Base class for every stage-attributed code_interpreter failure.

Subclasses RuntimeError deliberately: every failure this taxonomy replaces was raised as a bare RuntimeError before, so existing except RuntimeError callers keep working while new callers can except CodeInterpreterError and branch on stage / transient.

Attributes:

Name Type Description
stage Stage

The SDLC stage at which the failure occurred.

recovery RecoveryInfo

retryable is transient as it reads when the error is built.

debug_info SandboxDebugInfo

stage, plus the masked type, message and traceback of original_error when one is given.

Initialize the error with a stage and an optional transience classifier.

Parameters:

Name Type Description Default
message str | None

Human-readable, user-facing message. Secrets in it are masked, so a raise site can embed provider text (f"...: {e}") as is. Defaults to None, which uses the class's default_message.

None
stage Stage

The stage at which the failure occurred.

required
classifier TransientClassifier | None

A reference to the transient predicate to apply across the __cause__ chain. Defaults to None, which resolves to BaseSandbox._is_transient_create_error (#5418). This is a reference to the single source of truth, never a second classifier or a stored boolean.

None
original_error BaseException | None

The provider error that caused this one. It becomes __cause__, so recovery sees it, and its masked type, message and traceback go to debug_info. It is not passed to BaseError as is, because that would store its text unmasked whenever the host app installs no masking policy. Defaults to None.

None

transient property

Whether this failure is transient and worth retrying.

Walks this error and its __cause__ chain, applying #5418's classifier. Stops at an exception already checked, so a self-caused SDK error (raise e from e) cannot loop it. No parallel classification and no stored flag — the verdict is derived on read.

Returns:

Name Type Description
bool bool

True if any exception in the chain is classified transient.

SandboxDebugInfo

Bases: DebugInfo

The debug_info of a stage-attributed sandbox error.

Attributes:

Name Type Description
stage str

The Stage value at which the failure occurred.

SandboxExecutionError(message=None, *, stage, classifier=None, original_error=None)

Bases: CodeInterpreterError

Code/command execution or package installation failed after start.

SandboxImportError(message=None, *, debug_info=None, recovery=None, original_error=None)

Bases: BaseSandboxError, ImportError

Raised when the SDK of a sandbox provider is not installed.

Attributes:

Name Type Description
code str

Stable error code, GL-SBX-IMPORT.

default_message str

Default message, "A sandbox provider SDK is not installed. ..."

SandboxNotInitializedError(message=None, **kwargs)

Bases: CodeInterpreterError

An operation was attempted before the sandbox was initialized/started.

Initialize with the shared not-initialized message and NOT_INITIALIZED stage.

Parameters:

Name Type Description Default
message str | None

Human-readable message. Defaults to None, which uses default_message.

None
**kwargs Any

Forwarded to CodeInterpreterError (e.g. classifier).

{}

SandboxStartError(message=None, *, stage, classifier=None, original_error=None)

Bases: CodeInterpreterError

A sandbox failed to start, attributed to the specific start stage.

SandboxTerminateError(message=None, *, stage, classifier=None, original_error=None)

Bases: CodeInterpreterError

Teardown failed after every retry (stage is TERMINATE).

Replaces the provider SDK's raw exception, which is preserved as __cause__. The sandbox may still be alive on the server, so providers keep their handle for the caller to retry.

SandboxValueError(message=None, *, debug_info=None, recovery=None, original_error=None)

Bases: BaseSandboxError, ValueError

Raised when a sandbox or template builder argument or setting is invalid.

Attributes:

Name Type Description
code str

Stable error code, GL-SBX-VALIDATION.

default_message str

Default message, "A sandbox argument or setting is invalid. ..."

Stage

Bases: StrEnum

The stage of the code_interpreter SDLC at which a failure occurred.

The string value is recorded as debug_info["stage"] on every taxonomy error, and as the stage log field (extra={"stage": stage}) on failures logged without one, so keep the values stable and queryable.

TemplateBuildError(message=None, *, stage, classifier=None, original_error=None)

Bases: CodeInterpreterError

A template build/ensure failed (stage is typically TEMPLATE_BUILD).