All Python exceptions raised by ELIPS derive from elips.ElipsError. The C++ engine exceptions are mapped cleanly to idiomatic Python exception classes.

Overview

ELIPS uses specific exception types to allow precise error catching and retry logic for concurrent file locks, invalid vector dimensions, transaction aborted rollbacks, or disk space issues.

Exception Hierarchy

python

ElipsError
├── LockConflictError       # Raised when file lock cannot be acquired
├── ValidationError          # Raised on dimension mismatch or malformed filter
├── TransactionError        # Raised when a transaction commit fails
├── VaultSealedError        # Raised on write attempt to closed/sealed vault
├── ReadOnlyError           # Raised on mutation attempt in read-only mode
├── DiskError               # Raised on WAL or storage I/O errors
└── GpuError                # Raised on GPU device memory allocation failure

LockConflictError

Raised when another OS process holds an exclusive write lock on the database directory.

python

import elips
import time

def acquire_with_retry(db_path: str, max_retries: int = 5):
    for attempt in range(max_retries):
        try:
            return elips.connect(db_path, dimension=128)
        except elips.LockConflictError:
            print(f"Database locked by another process. Retrying in 1s ({attempt+1}/{max_retries})...")
            time.sleep(1.0)
    raise RuntimeError("Failed to acquire database lock.")

ValidationError

Raised when attempting to insert a vector whose dimension does not match the vault configuration, or when supplying a invalid metadata filter construct.

python

with elips.connect(":memory:", dimension=128) as engine:
    arena = engine.arena("vectors")
    try:
        # Invalid 3-dimensional vector passed to 128-dim vault
        arena.write(vector=[1.0, 2.0, 3.0])
    except elips.ValidationError as e:
        print(f"Validation failed: {e}")

TransactionError

Raised during txn.commit() if a batched write fails or a constraint is violated.

DiskError & GpuError

DiskError — Triggered by disk full events, permission denied on storage files, or corrupt WAL sequence numbers.
GpuError — Triggered by CUDA out-of-memory (`cudaErrorMemoryAllocation`) or missing GPU hardware drivers.

Retry Strategies & Best Practices

In multi-process worker environments (such as Gunicorn or Celery), wrap database opening in a LockConflictError retry loop. For transaction blocks, always catch TransactionError and invoke explicit rollback.