--- title: exceptions | CodeWeaver Docs description: API reference for codeweaver.core.exceptions url: "https://docs.knitli.com/api/core/exceptions" type: static generatedAt: "2026-04-17T17:21:08.022Z" --- # exceptions [Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[View in Markdown](/codeweaver/api/core/exceptions.md) [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F)[Share on X](https://x.com/intent/tweet?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F&text=exceptions)[Share on Threads](https://threads.net/intent/post?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F&text=exceptions)[Share on Bluesky](https://bsky.app/intent/compose?text=exceptions%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F)[Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F)[Share on Reddit](https://reddit.com/submit?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F&title=exceptions)[Share on Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F&t=exceptions)[Share on Email](mailto:?subject=exceptions&body=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F)[Share on WhatsApp](https://wa.me/?text=exceptions%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F)[Share on Telegram](https://t.me/share/url?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fcore%2Fexceptions%2F&text=exceptions) # `codeweaver.core.exceptions` [Section titled “codeweaver.core.exceptions”](#codeweavercoreexceptions) Unified exception hierarchy for CodeWeaver. This module provides a single, unified exception hierarchy to prevent exception proliferation. All CodeWeaver exceptions inherit from CodeWeaverError and are organized into five primary categories. ## Class: `CircularDependencyError` [Section titled “Class: CircularDependencyError”](#class-circulardependencyerror) Circular dependency detected error. Raised when a circular dependency is detected during dependency resolution. For example: ServiceA depends on ServiceB which depends on ServiceA. ## Class: `CodeWeaverDeveloperError` [Section titled “Class: CodeWeaverDeveloperError”](#class-codeweaverdevelopererror) Exception raised for when your friendly neighborhood codeweaver developer says “this could never happen…” — but it does. ## Class: `CodeWeaverError` [Section titled “Class: CodeWeaverError”](#class-codeweavererror) Base exception for all CodeWeaver errors. Provides structured error information including details and suggestions for resolution. Use `format_for_display()` to render a single exception node with full context for the user. Use `log_record()` to get a structured dict for structured-logging systems. `__str__` returns a concise message appropriate for tracebacks and plain log lines. ### Method: `format_for_display` [Section titled “Method: format_for_display”](#method-format_for_display) ** ``` format_for_display() ``` Format this exception node for user-facing display. Unlike `__str__`, this produces richly formatted output with all contextual information attached to *this* exception. When displaying an exception chain, call this only on the node you want to show in full; use `include_issue_info=True` only on the outermost display call so that the reporting boilerplate appears exactly once. Args: include_suggestions: Include the suggestions list. include_details: Include the details dict. include_issue_info: Append the alpha/issue-reporting boilerplate. Returns: Formatted string for display to the user. ### Method: `log_record` [Section titled “Method: log_record”](#method-log_record) ** ``` log_record() ``` Return a structured record for use with structured logging systems. Produces a plain `dict` containing all exception data so that logging back-ends (structlog, Python logging with a JSON formatter, etc.) can emit fully-structured log lines without parsing strings. Example:: logger.error(“Indexing failed”, **error.log_record()) Returns: Dict with `error_type`, `message`, `details`, `suggestions`, and `location` keys. ## Class: `CollectionNotFoundError` [Section titled “Class: CollectionNotFoundError”](#class-collectionnotfounderror) Collection not found error. Raised when attempting operations on a non-existent collection. ## Class: `ConfigurationError` [Section titled “Class: ConfigurationError”](#class-configurationerror) Configuration and settings errors. Raised when there are issues with configuration files, environment variables, settings validation, or provider configuration. ## Class: `ConfigurationLockError` [Section titled “Class: ConfigurationLockError”](#class-configurationlockerror) Collection configuration lock error. Raised when attempting to modify a collection’s configuration in a way that violates the collection’s policy (e.g., changing models when policy is STRICT, or switching to an incompatible model family when policy is FAMILY_AWARE). ## Class: `DatatypeMismatchError` [Section titled “Class: DatatypeMismatchError”](#class-datatypemismatcherror) Embedding datatype mismatch error. Raised when embedding datatypes don’t match the vector store collection configuration. ## Class: `DependencyInjectionError` [Section titled “Class: DependencyInjectionError”](#class-dependencyinjectionerror) Base exception for dependency injection system errors. Raised when there are issues with dependency resolution, registration, or lifecycle management in the DI container. ## Class: `DependencyNotAvailableError` [Section titled “Class: DependencyNotAvailableError”](#class-dependencynotavailableerror) Dependency not available error. Raised when a required optional dependency is not installed. ## Class: `DependencyResolutionError` [Section titled “Class: DependencyResolutionError”](#class-dependencyresolutionerror) Aggregate multiple dependency resolution errors. Raised when multiple dependency resolution errors occur and need to be reported together instead of failing fast on the first error. ## Class: `DimensionMismatchError` [Section titled “Class: DimensionMismatchError”](#class-dimensionmismatcherror) Embedding dimension mismatch error. Raised when embedding dimensions don’t match the vector store collection configuration. ## Class: `IndexingError` [Section titled “Class: IndexingError”](#class-indexingerror) File indexing and processing errors. Raised when there are issues with file discovery, content processing, or index building operations. ## Class: `InitializationError` [Section titled “Class: InitializationError”](#class-initializationerror) Initialization and startup errors. Raised when there are issues during application startup, such as missing dependencies, configuration errors, or environment setup problems. ## Class: `InvalidEmbeddingModelError` [Section titled “Class: InvalidEmbeddingModelError”](#class-invalidembeddingmodelerror) Exception raised when an invalid embedding model is encountered. ## Class: `LocationInfo` [Section titled “Class: LocationInfo”](#class-locationinfo) Location information for where an exception was raised. Attributes: filename: The name of the file line_number: The line number in the file ### Method: `from_frame` [Section titled “Method: from_frame”](#method-from_frame) ** ``` from_frame() ``` Create LocationInfo from a stack frame. Args: frame: The stack frame to inspect (default: 2) Returns: LocationInfo instance or None if unavailable. ## Class: `MissingValueError` [Section titled “Class: MissingValueError”](#class-missingvalueerror) Missing value errors. Raised when a required value is missing in the context of an operation. This is a specific case of validation error. ## Class: `ModelSwitchError` [Section titled “Class: ModelSwitchError”](#class-modelswitcherror) Model switching detection error. Raised when the system detects that the embedding model has changed from what was used to create the existing vector store collection. ## Class: `NodeParsingFailureError` [Section titled “Class: NodeParsingFailureError”](#class-nodeparsingfailureerror) Node parsing failure error. Raised when there is a failure in parsing nodes from the source files. ## Class: `PersistenceError` [Section titled “Class: PersistenceError”](#class-persistenceerror) Persistence operation error. Raised when in-memory provider persistence operations fail. ## Class: `ProviderError` [Section titled “Class: ProviderError”](#class-providererror) Provider integration errors. Raised when there are issues with embedding providers, vector stores, or other external service integrations. ## Class: `ProviderSwitchError` [Section titled “Class: ProviderSwitchError”](#class-providerswitcherror) Provider switching detection error. Raised when the system detects that the vector store collection was created with a different provider than the currently configured one. ## Class: `QueryError` [Section titled “Class: QueryError”](#class-queryerror) Query processing and search errors. Raised when there are issues with query validation, search execution, or result processing. ## Class: `RerankingProviderError` [Section titled “Class: RerankingProviderError”](#class-rerankingprovidererror) Reranking provider errors. Raised when there are issues specific to the reranking provider, such as invalid input formats, failed API calls, or unexpected response structures. ## Class: `ScopeViolationError` [Section titled “Class: ScopeViolationError”](#class-scopeviolationerror) Dependency scope violation error. Raised when a dependency violates scope rules, such as a request-scoped dependency depending on a function-scoped dependency. ## Class: `UnresolvableDependencyError` [Section titled “Class: UnresolvableDependencyError”](#class-unresolvabledependencyerror) Unresolvable dependency error. Raised when a dependency cannot be resolved because it’s not registered or doesn’t have a valid factory. ## Class: `ValidationError` [Section titled “Class: ValidationError”](#class-validationerror) Input validation and schema errors. Raised when there are issues with input validation, data model validation, or schema compliance.