Troubleshooting

Use this guide to diagnose and resolve issues with VectorAI DB. Start with the quick-reference table to identify your symptom, then follow the detailed steps for your issue.

Diagnostic checklist

Before diving into specific issues, verify the following:

Server is running and reachable (docker ps, nc -zv)
Configuration file is valid (--validate)
Data directory is writable and mounted
Collection contains data (points_count > 0)
Vector dimensions match query input
Logs don’t show startup errors

These checks resolve the majority of issues without deeper debugging.

Quick reference: common issues

The following table lists common symptoms, their likely causes, and links to the relevant sections in this guide.

Symptom	Likely cause	Jump to
Cannot connect to server	Container not running, wrong host/port	Connection issues
`UNAVAILABLE` error from SDK	Server starting up, network blocked	Connection issues
Search returns no results	Empty collection, wrong query vector dimensions	Search issues
Search results have poor quality	Low `hnsw_ef`, unoptimized index	Search quality
Slow ingestion	High `hnsw_ef_construction`, insufficient memory	Performance issues
Slow queries	Low `hnsw_ef`, cold index	Performance issues
Container exits immediately	Config error, missing license file	Startup failures
High memory usage	Large number of vectors, high concurrency, indexing workload, insufficient RAM	Memory issues
Data lost after restart	No persistent volume mounted	Data persistence

Connection issues

The following sections describe how to diagnose and fix connection failures.

Server not reachable

Follow these steps to verify the container is running and reachable.

Confirm the container is running

docker ps | grep vectorai

If the container is not listed, start it:

docker start <container-id>

Check the port binding

Verify port 6574 is exposed:

docker port <container-id>

Expected output: 6574/tcp -> 0.0.0.0:6574

Test connectivity from the host

nc -zv localhost 6574

If this fails, check for firewall rules or other processes using the port:

lsof -i :6574

Check server logs for binding errors

docker logs <container-id> | grep -E "error|bind|listen"

`UNAVAILABLE` error from SDK

This error indicates the client cannot reach the server. In addition to the steps above:

Confirm the host and port passed to VectorAIClient match the container binding
If connecting from another container, use the Docker network service name instead of localhost:
client = VectorAIClient("vectorai:6574") # Docker Compose service name
Check that TLS settings match — if the server has TLS enabled, the client must also enable TLS

Search issues

The following sections describe how to diagnose and fix problems with search results.

Search returns no results

The following table lists checks to perform when a search returns no results.

Check	Action
Collection is empty	Run `client.collections.get_info(name)` and check `points_count`
Query vector has wrong dimensions	Confirm dimensions match `collection.vectors_config.size`
Filter is too restrictive	Remove the filter and retry to isolate the issue
Collection is still indexing	Check index status in the GUI or via `get_collection_info`

Verify collection state

Use the following code to inspect the current state of a collection, including point count, indexed vector count, and status:

from actian_vectorai import VectorAIClient

with VectorAIClient("localhost:6574") as client:
    info = client.collections.get_info("my-collection")
    print(f"Points:  {info.points_count}")
    print(f"Indexed: {info.indexed_vectors_count}")
    print(f"Status:  {info.status}")

If indexed_vectors_count is lower than points_count, then the index is still building. Wait for indexing to complete before evaluating search quality.

Search quality

If search returns results but they are inaccurate or irrelevant, then the issue is usually related to index parameters, distance metrics, or embedding configuration.

Poor recall or irrelevant results

Expand each section for details on how to tune search parameters and verify your embedding configuration.

Increase hnsw_ef for higher recall

hnsw_ef controls how many candidates the HNSW graph explores during search. Increase it to trade speed for better recall:

from actian_vectorai import SearchParams

results = client.points.search(
    "my-collection",
    vector=query_embedding,
    limit=10,
    params=SearchParams(hnsw_ef=128)   # Override server default
)

Check the distance metric

Verify that the collection’s distance metric matches the one used to train your embedding model:

info = client.collections.get_info("my-collection")
print(info.config.params.vectors.distance)
# Should match your embedding model's expected metric

Common mismatch: using Cosine with embeddings trained for Dot product.

Verify embedding normalization

Cosine similarity requires unit-normalized vectors. If your embedding model does not normalize by default, normalize before inserting and before querying:

import numpy as np

def normalize(v):
    norm = np.linalg.norm(v)
    return (v / norm).tolist() if norm > 0 else v

embedding = normalize(raw_embedding)

Performance issues

The following sections describe how to identify and resolve slow ingestion and slow query performance.

Slow ingestion

The following table lists common causes of slow ingestion and recommended solutions.

Cause	Solution
High `hnsw_ef_construction`	Reduce to 100 for bulk loads; increase after
Inserting points one by one	Batch inserts — use lists of 100–1000 points per call
Insufficient memory	Increase container memory limit

Slow queries

The following table lists common causes of slow queries and recommended solutions.

Cause	Solution
High `hnsw_ef`	Lower to 64 for faster queries at slightly lower recall
Cold start after restart	Run a few warm-up queries before benchmarking
Payload filters on large collections	Create a payload index on filtered fields

Startup failures

The following section describes how to diagnose and fix container startup errors.

Container exits immediately

Use the following command to check logs for the error.

docker logs <container-id>

The following table lists common log messages and their fixes.

Log message	Cause	Fix
`failed to load config`	Malformed `config.yaml`	Validate YAML syntax
`license file not found`	Wrong `VECTORAI_LICENSE_FILE` path	Check volume mount path
`address already in use`	Port 6574 taken by another process	Stop the other process or change the port
`permission denied: data_dir`	Data directory not writable	Fix directory ownership: `chown -R 1000:1000 /data`

Use logs to diagnose issues

VectorAI DB logs provide the fastest way to identify root causes. Common patterns:

error → configuration or runtime failure
warn → potential performance or data issues
info → normal operation (useful for tracing flow)

Example:

docker logs <container-id> | grep -i error

Memory issues

Memory consumption depends on the number of vectors, their dimensionality, concurrency, and the HNSW index configuration. Use the checks below to identify what is driving high usage.

High memory usage

High memory usage usually becomes more noticeable when:

The collection contains a large number of vectors
Vector dimensionality is high
Query concurrency is high
The index graph maintains more connectivity between nodes

What is `m`?

In an HNSW index, m refers to the number of edges each node maintains in the graph. In practical terms:

Higher m usually improves recall by increasing graph connectivity
Higher m also increases memory usage and index build cost
Lower m reduces memory overhead but may lower search quality

In VectorAI DB, m should be understood as an index-structure concept rather than a general-purpose tuning setting for all deployments. For more background, see Vector index concepts.

Data persistence

By default, Docker containers store data in a writable layer that is discarded when the container is removed. Mount a volume to preserve data across restarts.

Data lost after container restart

Ensure a volume is mounted to the data directory. Without a volume, all data is stored in the container’s writable layer and is lost when the container is removed:

# Correct — data persists on the host
docker run -d --name vectorai \
  -v ./local_data:/var/lib/actian-vectorai \
  -p 6573-6575:6573-6575 \
  -e ACTIAN_VECTORAI_ACCEPT_EULA=YES \
  actian/vectorai:latest

# Incorrect — data lost on container removal
docker run actian/vectorai:latest

Verify the volume mount:

docker inspect <container-id> | grep -A 10 Mounts

Next steps

Explore these related guides to learn more.

Error handling

Handle specific gRPC error codes in your application code.

Docker installation

Container setup, volume mounts, and Docker Compose configuration.

HNSW indexing

Configure index parameters that affect search quality and performance.

Get started

SDKs

Guides

Integrations

Reference

Diagnostic checklist

Quick reference: common issues

Connection issues

Server not reachable

`UNAVAILABLE` error from SDK

Search issues

Search returns no results

Verify collection state

Search quality

Poor recall or irrelevant results

Performance issues

Slow ingestion

Slow queries

Startup failures

Container exits immediately

Use logs to diagnose issues

Memory issues

High memory usage

What is `m`?

Data persistence

Data lost after container restart

Next steps

Error handling

Docker installation

HNSW indexing

​Diagnostic checklist

​Quick reference: common issues

​Connection issues

​Server not reachable

​UNAVAILABLE error from SDK

​Search issues

​Search returns no results

​Verify collection state

​Search quality

​Poor recall or irrelevant results

​Performance issues

​Slow ingestion

​Slow queries

​Startup failures

​Container exits immediately

​Use logs to diagnose issues

​Memory issues

​High memory usage

​What is m?

​Data persistence

​Data lost after container restart

​Next steps

Error handling

Docker installation

HNSW indexing

Diagnostic checklist

Quick reference: common issues

Connection issues

Server not reachable

`UNAVAILABLE` error from SDK

Search issues

Search returns no results

Verify collection state

Search quality

Poor recall or irrelevant results

Performance issues

Slow ingestion

Slow queries

Startup failures

Container exits immediately

Use logs to diagnose issues

Memory issues

High memory usage

What is `m`?

Data persistence

Data lost after container restart

Next steps