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
|
|
debug_info |
SandboxDebugInfo
|
|
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 ( |
None
|
stage
|
Stage
|
The stage at which the failure occurred. |
required |
classifier
|
TransientClassifier | None
|
A reference to the transient
predicate to apply across the |
None
|
original_error
|
BaseException | None
|
The provider error that caused this one. It
becomes |
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 |
SandboxExecutionError(message=None, *, stage, classifier=None, original_error=None)
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, |
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
|
None
|
**kwargs
|
Any
|
Forwarded to |
{}
|
SandboxStartError(message=None, *, stage, classifier=None, original_error=None)
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, |
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.