Error handling

Understand error codes and exception types returned by VectorAI DB and how to handle them in your application.

VectorAI DB uses standard transport status codes and the Python SDK maps them to typed exceptions. Catch specific exceptions when you can, and use VectorAIError as the application-level catch-all.

SDK exceptions	actian_vectorai.exceptions module
Base exception	VectorAIError
Retry helpers	is_retryable(error), get_retry_delay(error)

Python SDK exceptions

The current Python SDK exposes these exception classes for common application handling.

Exception class	Typical cause	Useful fields
CollectionNotFoundError	A collection does not exist	collection_name, code, message
CollectionExistsError	Creating a collection that already exists	collection_name, code, message
ConnectionError	Server is unavailable or the channel failed	code, message, details
ConnectionTimeoutError	Connection attempt timed out	address, timeout, code, message
RateLimitError	Server rate limit or quota exceeded	retry_after, code, message
TimeoutError	RPC deadline exceeded	timeout, operation, code, message
UnimplementedError	The server does not implement the operation	operation, code, message
VectorAIError	Base class for SDK errors	code, message, details, operation

Catch specific exceptions

Use the namespaced SDK APIs in examples and production code. Collections live under client.collections, and vector search lives under client.points.

from actian_vectorai import (
    CollectionNotFoundError,
    TimeoutError,
    UnimplementedError,
    VectorAIClient,
    VectorAIError,
    get_retry_delay,
    is_retryable,
)

query = [0.1] * 128

with VectorAIClient("localhost:6574") as client:
    try:
        results = client.points.search("products", vector=query, limit=10)
    except CollectionNotFoundError as error:
        print(f"Collection '{error.collection_name}' not found")
    except UnimplementedError as error:
        print(f"Operation '{error.operation}' is not supported by this server")
    except TimeoutError:
        print("Request timed out; try increasing the per-call timeout")
    except VectorAIError as error:
        if is_retryable(error):
            delay = get_retry_delay(error, attempt=1)
            print(f"Transient error, retry after {delay:.1f}s")
        else:
            raise

Create a collection idempotently

Catch CollectionExistsError to skip creation when a collection is already present.

from actian_vectorai import (
    CollectionExistsError,
    Distance,
    VectorAIClient,
    VectorParams,
)

with VectorAIClient("localhost:6574") as client:
    try:
        client.collections.create(
            "product-embeddings",
            vectors_config=VectorParams(size=1536, distance=Distance.Cosine),
        )
    except CollectionExistsError:
        pass

Retry transient failures

Use exponential backoff for retryable errors. The helper functions understand SDK exception types, including ConnectionError, RateLimitError, and TimeoutError.

import time

from actian_vectorai import VectorAIError, get_retry_delay, is_retryable


def search_with_retry(client, collection_name, query_vector, limit=10, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.points.search(
                collection_name,
                vector=query_vector,
                limit=limit,
            )
        except VectorAIError as error:
            if not is_retryable(error) or attempt == max_retries - 1:
                raise
            time.sleep(get_retry_delay(error, attempt=attempt + 1))

Inspect error details

Every SDK exception exposes message, code, details, and operation where available. Use these fields for logging and custom handling.

from actian_vectorai import VectorAIError

try:
    client.points.search("products", vector=[0.1] * 128, limit=10)
except VectorAIError as error:
    print(f"Code:      {error.code}")
    print(f"Message:   {error.message}")
    print(f"Details:   {error.details}")
    print(f"Operation: {error.operation}")

Common error messages

Collection not found

Cause: The collection name is misspelled, or the collection was deleted.

Fix: Call client.collections.list() to verify the collection exists before operating on it.

collections = client.collections.list()
print(collections)

Wrong vector dimensions

Cause: The query vector or inserted vector has a different number of dimensions than the collection configuration.

Fix: Confirm the embedding model and collection dimensions match.

Authentication failure

Cause: The server has authentication enabled but the client did not supply a valid access token.

Fix: Pass the configured token to VectorAIClient or set ACTIAN_VECTORAI_ACCESS_TOKEN.

Server unavailable

Cause: VectorAI DB is not running, is still starting, or is unreachable at the configured address.

Fix: Confirm the server is reachable at localhost:6574 or set ACTIAN_VECTORAI_URL.

Next steps

Troubleshooting

Diagnose connection, search, and startup issues.

Python SDK

Get started with the Python SDK.