Troubleshooting

Identify and fix common operational problems with VectorAI DB using guided diagnostic steps.

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

Quick reference: common issues

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

Server not reachable

1. Confirm the container is running

   docker ps | grep vectorai
   

   If the container is not listed, start it:

   docker start <container-id>
   
2. Check the port binding

   Verify port 6574 is exposed:

   docker port <container-id>
   

   Expected output: 6574/tcp -> 0.0.0.0:6574

3. 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
   
4. 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

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

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, 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, the issue is usually related to index parameters, distance metrics, or embedding configuration.

Poor recall or irrelevant results

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

Slow ingestion

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

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

Container exits immediately

docker logs <container-id>

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)

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.

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.

• 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

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:

# 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

Error handling

Handle specific gRPC error codes in your application code.

Docker setup

Container setup, volume mounts, and Docker Compose configuration.

HNSW indexing

Configure index parameters that affect search quality and performance.