Exceptions¶
Every exception VectrixDB raises deliberately derives from VectrixError.
See Handle errors for how to use them.
vectrixdb.exceptions
¶
VectrixDB exception hierarchy.
Every exception raised deliberately by VectrixDB derives from :class:VectrixError,
so callers can insulate themselves from the library with a single except::
from vectrixdb import VectrixError
try:
results = db.search("query")
except VectrixError as exc:
log.warning("vector search unavailable: %s", exc)
Backend failures are wrapped rather than swallowed. A read that cannot reach its
storage backend raises :class:StorageOperationError; it never reports an empty
result, because "the collection is empty" and "the database is unreachable" must
not look the same to a caller.
Guidance for choosing an exception when adding code:
- The caller asked for something that does not exist ->
*NotFoundError. - The caller passed something invalid -> :class:
ConfigurationErroror :class:DimensionMismatchError. - A dependency, network hop, or driver failed -> :class:
StorageErrorsubclass, raisedfromthe original exception so the traceback is preserved.
VectrixError
¶
Bases: Exception
Base class for every error raised by VectrixDB.
Catching this catches anything the library raises on purpose. It does not
catch programming errors such as TypeError, which are allowed to
propagate unchanged.
ConfigurationError
¶
Bases: VectrixError
A configuration value is missing, malformed, or mutually exclusive.
DependencyError
¶
Bases: VectrixError
An optional dependency is required for this code path but not installed.
Raised instead of a bare ImportError so the message can name the extra
that provides the missing package.
ExtractionError
¶
Bases: VectrixError
Turning a file into text failed, and nothing was written.
One type for every way that goes wrong, an extractor that raised, an
endpoint that answered 500, a reply whose page offsets run past its own
text, so the ingestion worker and the REST route catch this and nothing
else. route and status are set when an endpoint was involved.
TranslationError
¶
Bases: VectrixError
A translation, a language detection or the language list failed.
Its own type, apart from ExtractionError, because a translation is
something a caller asked for and is waiting on, not a step inside
reading a file, and it is caught in different places. route is the
operation, translate, detect or languages, and status the
service's answer when there was one.
StorageError
¶
Bases: VectrixError
Base class for storage backend failures.
StorageConnectionError
¶
Bases: StorageError
The storage backend could not be reached or authenticated against.
StorageOperationError
¶
Bases: StorageError
A storage operation failed.
Carries the backend name and the operation that failed so the message is actionable without reading a traceback.
CollectionNotFoundError
¶
CollectionAlreadyExistsError
¶
DocumentNotFoundError
¶
DimensionMismatchError
¶
SearchError
¶
Bases: VectrixError
A search could not be completed.
GraphUnavailable
¶
Bases: SearchError
Graph search could not run because there is no graph to run it on.
Raised when the pipeline was never built, or has no searcher for the
requested search type. Vectrix.search(mode="graph") treats this as
ordinary: it falls back to vector results and records the reason in
Results.degraded. Any other error out of the graph is a real failure
and is reported as one.
QuantizationError
¶
Bases: VectrixError
A vector could not be quantized or dequantized.
IndexBuildError
¶
Bases: VectrixError
An index could not be built or loaded.
Named IndexBuildError rather than IndexError so it does not shadow
the builtin.
ModelError
¶
Bases: VectrixError
Base class for embedded model failures.
ModelNotFoundError
¶
Bases: ModelError, FileNotFoundError
A requested model is not bundled and is not present on disk.
Also a FileNotFoundError, which is what the model loader used to
raise. Callers catching either keep working, and the promise that one
except VectrixError covers the library now holds on this path too.
ModelDownloadError
¶
Bases: ModelError
A model could not be downloaded.
ModelMismatchWarning
¶
Bases: UserWarning
A collection was opened with a different embedding model than it was
built with. Queries embed with one model and documents with another, so
scores are meaningless until reembed() runs.
InvalidCollectionName
¶
Bases: VectrixError, ValueError
A collection name cannot be used as a directory name.
The name becomes a directory under the database path, so separators,
parent references and reserved device names are refused. Also a
ValueError, which is what this used to raise, so existing handlers
keep working.
SparseModelUnavailableWarning
¶
Bases: UserWarning
A named sparse model cannot be the one that actually runs.
The sparse half of a hybrid search reaches a learned model only through a
storage backend that implements its own hybrid search. On a local
collection it is the bundled BM25 index whatever sparse_model says,
and the results are BM25 results.
CollectionLoadWarning
¶
Bases: UserWarning
A registered collection would not open, so it is not in the database.
The rest of the database opened normally and the collection's data on
disk was left alone. VectrixDB.failed_collections names it and says
why, and asking for it by name raises rather than reporting it missing.
PolicyError
¶
Bases: VectrixError
A policied collection could not answer, and said so.
Note what does not live under here: there is no AccessDenied. A
denial is an empty result, never an exception. An exception a caller can
catch and tell apart from "nothing matched" is itself the side channel,
and it defeats an ethical wall however careful the layer above is. Every
subclass below is a refusal to run, not a refusal of access.
PolicyDefinitionError
¶
Bases: PolicyError, ValueError
The policy itself is malformed, so nothing was evaluated.
PrincipalRequired
¶
Bases: PolicyError
This collection carries a policy and the search supplied no principal.
The whole point of binding a policy to the collection is that forgetting it cannot silently return everything, so it raises instead.
PrincipalIncomplete
¶
Bases: PolicyError
The principal is missing a key the policy names.
This is the host's entitlement resolver failing, not a user without permission, and the difference matters operationally: failing closed is correct, but it belongs on a pager rather than in the denial count where it would look like a busy afternoon.
PolicyMismatch
¶
Bases: PolicyError
The collection's stored policy is not the one it was opened with.
A policy travels with the data it governs. Opening a collection under a different rule set is either a deployment that has drifted or an attempt to relax a control by reopening, and neither should be a silent success.
CollectionStoreUnavailable
¶
Bases: PolicyError
The collection records could not be read, and nothing read earlier can stand in.
A collection's rules live in one record every server reads. When that record cannot be read and no copy of it is held from a moment ago, the search does not run: running it without the rules is the one outcome that is worse than not answering.
PushdownUnavailable
¶
Bases: PolicyError
The policy requires engine-side filtering and this backend cannot.
A backend that fetches candidates and filters them afterwards still returns the right documents, but the filter is no longer the thing the engine enforced, and the number of rows examined varies with how selective the entitlements are. Where that matters the policy says so and this refuses rather than quietly degrading.
AuditUnavailable
¶
Bases: PolicyError
A decision record could not be stored, and the policy is to deny.
The other choice is to answer and spool, which is why neither is a default. Where an unaudited answer is worse than no answer, this is what that looks like.
PolicyNotEnforcedWarning
¶
Bases: UserWarning
A collection with an entitlement policy was searched without it.
Policies are enforced by Vectrix. Anything that reaches a
Collection directly, which is what the REST server and everything
else built on VectrixDB does, sees every document the query matches
with the policy sitting unread in the collection's metadata.
The warning exists because silence is the worst of both: the collection looks protected and is not.
MetadataContractError
¶
Bases: PolicyError, ValueError
A document arrived that the policy could never show anybody.
Two spellings of one bug. The field the policy decides by is absent, or it is there and holds something the rule cannot reach a verdict on, like a classification rank written as "high". Either way the rule is false for every principal, the chunk is invisible to everybody, and the symptom reads as a permissions problem.
Caught at ingestion rather than at query time because of where the two failures land. Written, somebody spends an afternoon in the entitlement resolver. Refused, it is a pipeline bug with a stack trace pointing at the pipeline.
MetadataContractWarning
¶
Bases: UserWarning
A document was written without a field the policy decides by.
What on_incomplete_document="warn" produces: the write goes through so
an existing collection can be backfilled, and the chunk stays invisible to
every principal until it is.
ExtractionQualityError
¶
Bases: VectrixError, ValueError
A document arrived whose text reads as a failed extraction.
The chunk that passes every schema check and destroys retrieval: a scanned page that OCRed into fragments and glyph noise. Refused at the write, where the stack trace points at the pipeline, rather than found later as a ranking problem nobody can explain.
ExtractionQualityWarning
¶
Bases: UserWarning
A document whose text reads as a failed extraction was written anyway.