Error Reference

Error Reference¶

All error types thrown by the library across all languages.

KreuzbergError¶

Main error type for all Kreuzberg operations.

All errors in Kreuzberg use this enum, which preserves error chains and provides context for debugging.

Variants¶

Io - File system and I/O errors (always bubble up)
Parsing - Document parsing errors (corrupt files, unsupported features)
Ocr - OCR processing errors
Validation - Input validation errors (invalid paths, config, parameters)
Cache - Cache operation errors (non-fatal, can be ignored)
ImageProcessing - Image manipulation errors
Serialization - JSON/MessagePack serialization errors
MissingDependency - Missing optional dependencies (tesseract, etc.)
Plugin - Plugin-specific errors
LockPoisoned - Mutex/RwLock poisoning (should not happen in normal operation)
UnsupportedFormat - Unsupported MIME type or file format
Other - Catch-all for uncommon errors

Variant	Message	Description
`Io`	IO error:	A file system or I/O operation failed. These errors always bubble up unchanged.
`Parsing`	Parsing error:	Document parsing failed (e.g. corrupt file, unsupported format feature).
`Ocr`	OCR error:	An OCR engine returned an error or produced unusable output.
`Validation`	Validation error:	Invalid configuration or input parameters were supplied.
`Cache`	Cache error:	A cache read or write operation failed.
`ImageProcessing`	Image processing error:	An image manipulation operation (resize, decode, DPI conversion) failed.
`Serialization`	Serialization error:	JSON or MessagePack serialization/deserialization failed.
`MissingDependency`	Missing dependency:	A required optional system dependency (e.g. `tesseract`) was not found.
`Plugin`	Plugin error in '{plugin_name}':	A registered plugin returned an error during extraction.
`LockPoisoned`	Lock poisoned:	An internal `Mutex` or `RwLock` was found in a poisoned state.
`UnsupportedFormat`	Unsupported format:	The document's MIME type is not supported by any registered extractor.
`Embedding`	Embedding error:	The embedding model or embedding pipeline returned an error.
`Reranking`	Reranking error:	The reranker model or reranking pipeline returned an error. Since v5.0.
`Transcription`	Transcription error:	Audio/video transcription failed.
`Timeout`	Extraction timed out after {elapsed_ms}ms (limit: {limit_ms}ms)	The extraction operation exceeded the configured time limit.
`Cancelled`	Extraction cancelled	The extraction was cancelled via a `CancellationToken`.
`Security`	Security violation:	A security policy was violated (e.g. zip bomb, oversized archive).
`Other`	{0}	A catch-all for uncommon errors that do not fit another variant.

HeuristicsError¶

Errors that can occur during heuristics analysis.

Variant	Message	Description
`ConfigError`	Invalid heuristics configuration:	Invalid configuration value.
`PdfAnalysisError`	PDF analysis failed:	PDF analysis step failed (only when `heuristics-pdf` feature is active).

LoadError¶

Errors produced while loading or validating a preset file.

Variant	Message	Description
`Parse`	preset {path}: failed to parse JSON: {source}	The file is not valid JSON.
`SchemaValidation`	preset {path}: failed meta-schema validation: {errors}	The file parses as JSON but does not validate against the meta-schema.
`Deserialize`	preset {path}: failed to deserialize after validation: {source}	The file validates but cannot be deserialized into `Preset`.
`IdMismatch`	preset {path}: id `{declared}` must match file path stem `{expected}`	The preset's declared `id` does not match its file-system location.
`BadMetaSchema`	meta-schema is invalid:	The meta-schema itself failed to compile.
`Io`	I/O error reading preset directory:	A filesystem I/O error occurred while reading a preset directory.

ResolveError¶

Errors produced while resolving a preset against caller overrides.

Variant	Message	Description
`SchemaNotObject`	custom schema must be a JSON object	A custom schema override was supplied but is not a JSON object.

Edit this page on GitHub