Skip to main content

Module error

kglite

Module error 

Source
Expand description

Typed error taxonomy for KGLite.

Phase A.2 of docs/history/bolt-implementation.md — replaces the prior “everything is a String then wrapped as PyValueError / PyRuntimeError” pattern with a structured KgError enum + a KgErrorCode classification. Existing per-module error types (SchemaError, ValidationError, ExprError) are preserved and bridged in via From impls — no taxonomy duplication.

§Why

  • Python consumers can except kglite.CypherSyntaxError: instead of grep’ing message strings.
  • Cypher parser line/col survives the boundary instead of being embedded in the formatted string.
  • Phase C.6 (Bolt FAILURE-code mapping) needs typed codes; landing them now means the whole engine surface is uniformly classified.
  • MCP server error responses gain structured codes; agents can react programmatically.

§Hierarchy

Every kglite-raised exception is a subclass of kglite.KgError. The Python class chain is defined in [crate::error_py] via PyO3’s create_exception! macro. The Rust KgError enum + the From<KgError> for PyErr impl at the boundary pick the most specific subclass for each variant.

Cypher: CypherSyntaxError, CypherTimeoutError, CypherExecutionError, CypherTypeMismatchError — all subclass CypherError which subclasses KgError.

Schema/Validation: SchemaError, ValidationError — subclass KgError directly.

Resource access: NodeNotFoundError, ConnectionNotFoundError, PropertyNotFoundError — subclass KgError.

File/IO: FileError, FileFormatError — subclass KgError.

Argument validation: ArgumentError, MissingArgumentError — subclass KgError.

Internal identity: InternerCollisionError reports a rejected persisted name-key collision. InternalError is reserved for invariants that should never trip (e.g. node-binding lookup guaranteed by upstream pattern match).

Enums§

KgError
The canonical error type for KGLite. Every fallible operation reachable from the public API returns Result<T, KgError> (directly or via ? from a From-convertible source type).
KgErrorCode
Canonical classification of every error KGLite raises.
SchemaErrorKindRepr
Wire-stable repr of SchemaErrorKind.

Type Aliases§

KgResult
Public convenience alias for downstream Rust callers that prefer a single KGLite result spelling. Engine internals use explicit result types where the error boundary benefits from being visible.