Exceptions

Typed errors raised by gllm-datastore for encryption, cache, embedding, and key management failures.

Each error keeps its previous builtin ancestry (RuntimeError or ValueError) so existing except clauses keep matching. Dynamic detail such as chunk IDs and the original error is carried in debug_info.

`BaseDatastoreError(message=None, *, debug_info=None)`

Bases: BaseError

Root of the normalized errors raised by gllm-datastore.

This class is abstract and is never raised directly. Every concrete subclass defines its own code (GLLM-DS-<NAME>) and default_message.

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`	`DatastoreDebugInfo`	Structured internal detail about this error.

`CacheEvictionCloseError(message=None, *, debug_info=None)`

Bases: BaseDatastoreError, RuntimeError

Raised when the cache eviction manager fails to close or stop.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-DS-CACHE-EVICTION-CLOSE`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`DatastoreDebugInfo`	Structured internal detail about this error.

`CacheEvictionStartError(message=None, *, debug_info=None)`

Bases: BaseDatastoreError, RuntimeError

Raised when the cache eviction manager fails to start.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-DS-CACHE-EVICTION-START`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`DatastoreDebugInfo`	Structured internal detail about this error.

`DatastoreDebugInfo`

Bases: DebugInfo

Structured internal detail attached to the errors raised by gllm-datastore.

Extends DebugInfo with the keys specific to datastore errors. This is a type-level contract only.

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.
`chunk_id`	`str`	ID of the chunk being processed, when the error relates to a chunk.
`stage`	`str`	Stage of the operation that failed, such as `content` or `metadata`.
`fields`	`list[str]`	Names of the fields that failed, when applicable.
`capability`	`str`	Name of the capability involved, when applicable.
`datastore_class`	`str`	Name of the datastore class involved, when applicable.

`DecryptionError(message=None, *, debug_info=None)`

Bases: BaseDatastoreError, RuntimeError

Raised when decrypting the content or metadata of a chunk fails.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-DS-DECRYPTION`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`DatastoreDebugInfo`	Structured internal detail, such as `chunk_id`, `stage`, and `fields`.

`EmbeddingInvocationError(message=None, *, debug_info=None)`

Bases: BaseDatastoreError, RuntimeError

Raised when embedding invocation still fails after all retries.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-DS-EMBEDDING-INVOCATION`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`DatastoreDebugInfo`	Structured internal detail about this error.

`EncryptionError(message=None, *, debug_info=None)`

Bases: BaseDatastoreError, RuntimeError

Raised when encrypting the content or metadata of a chunk fails.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-DS-ENCRYPTION`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`DatastoreDebugInfo`	Structured internal detail, such as `chunk_id`, `stage`, and `fields`.

`OpenBaoAuthenticationError(message=None, *, debug_info=None)`

Bases: BaseDatastoreError, ValueError

Raised when authenticating with OpenBao fails.

Attributes:

Name	Type	Description
`code`	`str`	Stable error code, `GLLM-DS-OPENBAO-AUTH`.
`default_message`	`str`	Message used when no message is given.
`message`	`str`	The message of this error.
`debug_info`	`DatastoreDebugInfo`	Structured internal detail about this error.