Skip to content

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.

  1. Every concrete subclass must define code using the format <PREFIX>-<LIB>-<NAME> (for example, GLLM-INF-AUTH or GL-SBX-TIMEOUT). <PREFIX> and <LIB> are each 2 to 5 capital letters. <NAME> is made of A-Z and 0-9 words joined by hyphens, such as RATE-LIMIT.
  2. Every concrete subclass must define default_message.
  3. Codes are registered at class definition and must be unique across all loaded libraries.
  4. Intermediate base classes that are never raised directly must pass abstract=True in the class statement.
  5. When combining BaseError with built-in exceptions, BaseError must 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 configure_error_masking, if any.

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 str(). Defaults to None.

recovery RecoveryInfo

Guidance on how to react to this error. Defaults to {"retryable": False}. A subclass may declare its own class-level default.

Initializes the error.

Parameters:

Name Type Description Default
message str | None

Message overriding default_message. Defaults to None.

None
debug_info DebugInfo | None

Structured internal detail. Defaults to None, which results in a DebugInfo containing only class_name.

None
recovery RecoveryInfo | None

Guidance replacing the class-level recovery for this instance, for example to carry a reported retry_after_seconds. Defaults to None, which uses the class-level recovery.

None
original_error BaseException | None

The raw error that caused this one. Its type, message, and traceback are recorded in debug_info and redacted by the installed masking policy. The traceback is recorded only when the error was raised. Defaults to None.

None

Raises:

Type Description
TypeError

If neither message nor default_message is available.

__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 default_message, has a missing or malformed code, or reuses a code registered by another class.

__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, GLLM-CORE-COMPONENT-DEFINITION.

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, GLLM-CORE-ATTRIBUTE.

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, GLLM-CORE-IMPORT.

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, GLLM-CORE-KEY.

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, GLLM-CORE-NOT-IMPLEMENTED.

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, GLLM-CORE-RUNTIME.

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, GLLM-CORE-TYPE.

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, GLLM-CORE-VALIDATION.

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 str() of the exception, or a <Type> (message unavailable: str() raised <Type>) note when str() raises, redacted by the installed masking policy. Always present.

code str | None

Stable error code of a BaseError, None for an abstract class.

recovery RecoveryInfo

Recovery guidance of a BaseError.

debug_info DebugInfo

Structured internal detail of a BaseError, already redacted at construction, without its traceback.

reference_id str | None

Diagnostic record identifier of a BaseError, None until a service sets it.

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 debug_info. Defaults to None.

None

__str__()

Returns the full error text that names the upstream tool.

Returns:

Name Type Description
str str

The error text.