Exceptions
Defines the shared base exception for normalized errors raised by SDK libraries.
BaseCoreError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: BaseError
Root of normalized errors raised by gllm-core itself.
Codes of concrete subclasses use the GLLM-CORE-<NAME> format. Subclasses that replace a raw built-in
raise also inherit that built-in (after BaseError), so existing except ValueError and except TypeError
handlers keep working.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str | None
|
Not set; concrete subclasses define their own code. |
default_message |
str | None
|
Not set; concrete subclasses define their own default message. |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
BaseError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: Exception
Root of normalized errors raised by SDK libraries.
- Every concrete subclass must define
codeusing the format<PREFIX>-<LIB>-<NAME>(for example,GLLM-INF-AUTHorGL-SBX-TIMEOUT).<PREFIX>and<LIB>are each 2 to 5 capital letters.<NAME>is made ofA-Zand0-9words joined by hyphens, such asRATE-LIMIT. - Every concrete subclass must define
default_message. - Codes are registered at class definition and must be unique across all loaded libraries.
- Intermediate base classes that are never raised directly must pass
abstract=Truein the class statement. - When combining
BaseErrorwith built-in exceptions,BaseErrormust come first, for example:class X(BaseError, ValueError).
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str | None
|
Stable error code. Defined by each concrete subclass. |
default_message |
str | None
|
Message used when no message is given. Defined by each concrete subclass. |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. Redacted at construction by the
policy installed through |
reference_id |
str | None
|
Identifier of the diagnostic record for this occurrence. Set by the consuming
service when it records the error; never generated by core. Not included in |
recovery |
RecoveryInfo
|
Guidance on how to react to this error. Defaults to |
Initializes the error.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str | None
|
Message overriding |
None
|
debug_info
|
DebugInfo | None
|
Structured internal detail. Defaults to None, which
results in a |
None
|
recovery
|
RecoveryInfo | None
|
Guidance replacing the class-level |
None
|
original_error
|
BaseException | None
|
The raw error that caused this one. Its type, message,
and traceback are recorded in |
None
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If neither |
__init_subclass__(abstract=False, **kwargs)
Validates and registers a concrete subclass.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
abstract
|
bool
|
Whether the subclass is an abstract base that is never raised directly. Defaults to False. |
False
|
**kwargs
|
Any
|
Additional class keyword arguments passed to the parent. |
{}
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If a concrete subclass lacks |
__str__()
Returns the error message.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The error message. |
ComponentDefinitionError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: CoreTypeError
Raised when a component class, its main method, or a dynamic component binding is defined incorrectly.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code, |
default_message |
str
|
Default message, "The component definition is invalid. ..." |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
CoreAttributeError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: BaseCoreError, AttributeError
Raised when a required attribute is missing from an object.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code, |
default_message |
str
|
Default message, "A required attribute is missing. ..." |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
CoreImportError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: BaseCoreError, ImportError
Raised when an optional dependency required by a feature is not installed.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code, |
default_message |
str
|
Default message, "A required dependency could not be imported. ..." |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
CoreKeyError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: BaseCoreError, KeyError
Raised when a required key is missing from a mapping or an unknown key is requested.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code, |
default_message |
str
|
Default message, "A required key is missing. Add the key to the input and try again." |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
CoreNotImplementedError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: BaseCoreError, NotImplementedError
Raised when functionality is not implemented in a subclass.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code, |
default_message |
str
|
Default message, "This functionality is not implemented. Override it in a subclass." |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
CoreRuntimeError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: BaseCoreError, RuntimeError
Raised when an operation fails at runtime.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code, |
default_message |
str
|
Default message, "A core operation failed at runtime. ..." |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
CoreTypeError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: BaseCoreError, TypeError
Raised when a value has an unsupported type.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code, |
default_message |
str
|
Default message, "The value has an unsupported type. ..." |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
CoreValueError(message=None, *, debug_info=None, recovery=None, original_error=None)
Bases: BaseCoreError, ValueError
Raised when a configuration, schema, or runtime binding value is invalid.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code, |
default_message |
str
|
Default message, "The configuration is invalid. Check the provided values and try again." |
message |
str
|
The message of this error. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
DebugInfo
Bases: TypedDict
Minimum schema of the debug_info attached to a BaseError.
This is a type-level contract only; no runtime validation is performed. Libraries may add extra keys
(e.g. response_detail, status_code) for their own errors.
Attributes:
| Name | Type | Description |
|---|---|---|
class_name |
str
|
Name of the exception class. Always present. |
error_type |
str
|
Type name of the original error, when one was caught. |
original_message |
str
|
Message of the original error, when one was caught. |
traceback |
str
|
Formatted traceback of the original error, when one was caught and had been raised. |
DebugInfoKeys
Constants for the keys of DebugInfo.
RecoveryInfo
Bases: TypedDict
Structured guidance for automated consumers on how to react to a BaseError.
This is a type-level contract only; no runtime validation is performed. Retry limits (attempt count, backoff,
total timeout) are policy owned by the caller, for example RetryConfig, and are not part of this schema.
Attributes:
| Name | Type | Description |
|---|---|---|
retryable |
bool
|
Whether retrying the same operation can succeed. Always present. |
retry_after_seconds |
int
|
Seconds to wait before retrying, when the source reported one. |
SerializedError
Bases: TypedDict
Snapshot of an exception, produced by serialize_exception.
This is a type-level contract only; no runtime validation is performed. The fields from code to
reference_id are present only for a BaseError.
Attributes:
| Name | Type | Description |
|---|---|---|
class_name |
str
|
Name of the exception class. Always present. |
message |
str
|
The |
code |
str | None
|
Stable error code of a |
recovery |
RecoveryInfo
|
Recovery guidance of a |
debug_info |
DebugInfo
|
Structured internal detail of a |
reference_id |
str | None
|
Diagnostic record identifier of a |
cause |
SerializedError
|
The next exception in the chain: the explicit cause, or else the implicit context unless it is suppressed. An implicit context may be unrelated to this exception. |
UpstreamToolError(tool_name, upstream_tool, message, *, cause=None)
Bases: BaseCoreError
Raised when an upstream MCP tool call fails.
The message attribute holds the raw upstream description, while str(error) returns the full text that
names the upstream tool.
Attributes:
| Name | Type | Description |
|---|---|---|
code |
str
|
Stable error code. |
default_message |
str
|
Message used when no message is given. |
tool_name |
str
|
Name of the exposed adapter tool. |
upstream_tool |
str
|
Name of the tool on the upstream server. |
message |
str
|
Human-readable error description. |
debug_info |
DebugInfo
|
Structured internal detail about this error. |
Initialize an UpstreamToolError.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_name
|
str
|
Name of the exposed adapter tool. |
required |
upstream_tool
|
str
|
Name of the tool on the upstream server. |
required |
message
|
str
|
Human-readable error description. |
required |
cause
|
BaseException | None
|
The underlying exception that caused this error. Its type,
message, and traceback are recorded in |
None
|
__str__()
Returns the full error text that names the upstream tool.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The error text. |