localvectordb.exceptions module

exception localvectordb.exceptions.BaseLocalVectorDBException

Bases: Exception

Base class for all LocalVectorDB exceptions.

exception localvectordb.exceptions.DatabaseError

Bases: BaseLocalVectorDBException

Raised for general database operation failures.

exception localvectordb.exceptions.DatabaseNotFoundError

Bases: DatabaseError, KeyError

Raised if the Database cannot be found

exception localvectordb.exceptions.MetadataFilterError

Bases: DatabaseError, ValueError

Raised when there’s an error in metadata filter specification or processing

exception localvectordb.exceptions.DuplicateDocumentIDError

Bases: DatabaseError, ValueError

Raised when inserting document(s) and the id(s) already exist

exception localvectordb.exceptions.IngestError(message: str, failures: Dict[str, str] | None = None, succeeded: List[str] | None = None)

Bases: DatabaseError

Raised by upsert/insert (and their async twins) when one or more documents fail to embed or write and errors="raise" (the default).

Each document is committed in its own transaction, so the documents that succeeded are durably persisted – their IDs are in succeeded. The documents that failed are in failures (doc_id -> error message). Pass errors="ignore" to suppress this and get best-effort ingestion that returns only the IDs that landed.

__init__(message: str, failures: Dict[str, str] | None = None, succeeded: List[str] | None = None)

exception localvectordb.exceptions.IndexIntegrityError

Bases: DatabaseError

Raised when the SQLite rows and the FAISS index disagree in a way that corrupts query results – notably duplicate faiss_id values, which cause one vector to be attributed to two different documents.

Recover with lvdb db <name> repair.

exception localvectordb.exceptions.UnsupportedIndexOperationError

Bases: DatabaseError

Raised when an operation is not supported by the configured FAISS index type.

Most commonly: IndexHNSWFlat cannot remove vectors, so documents cannot be deleted or replaced in a database backed by it.

exception localvectordb.exceptions.DocumentNotFoundError(message: str, missing_ids: str | List[str] | None = None)

Bases: DatabaseError, KeyError

Raised when one or more requested documents cannot be found

__init__(message: str, missing_ids: str | List[str] | None = None)

exception localvectordb.exceptions.PatchConflictError(message: str, expected: str | None = None, actual: str | None = None)

Bases: DatabaseError

Raised when a document patch’s expect_hash precondition does not match the stored content_hash – i.e. the document changed since the caller read it.

This is a distinct outcome from “document not found” and “no-op”: the document exists and the ops are valid, but applying them would clobber a concurrent write. Surfaces as HTTP 409 on the server.

__init__(message: str, expected: str | None = None, actual: str | None = None)

exception localvectordb.exceptions.PatchError

Bases: DatabaseError, ValueError

Raised when a document patch’s ops cannot be applied: an unmatched or ambiguous find, an out-of-range or overlapping splice, or a malformed op.

The whole patch fails atomically – no partial write. Surfaces as HTTP 422 on the server.

exception localvectordb.exceptions.EmbeddingError

Bases: BaseLocalVectorDBException, RuntimeError

Raised when an embedding provider fails to generate embeddings.

exception localvectordb.exceptions.ProviderHTTPError(message: str, status_code: int | None = None)

Bases: EmbeddingError

A provider HTTP failure that keeps its status code.

Providers used to report an API error as a bare RuntimeError built from the JSON error message, discarding the status. That made the error unclassifiable: EmbeddingProvider._should_retry matches on httpx types and a status code, so a 429 was never retried despite max_retries=3 and a docstring promising “automatic retry handling” – a bulk ingest died on a rate limit whose own message said “try again in 174ms”.

Subclasses EmbeddingError (and therefore RuntimeError), so any caller already catching those is unaffected.