Skip to main content
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.
SymptomLikely causeJump to
Cannot connect to serverContainer not running, wrong host/portConnection issues
UNAVAILABLE error from SDKServer starting up, network blockedConnection issues
Search returns no resultsEmpty collection, wrong query vector dimensionsSearch issues
Search results have poor qualityLow hnsw_ef, unoptimized indexSearch quality
Slow ingestionHigh hnsw_ef_construction, insufficient memoryPerformance issues
Slow queriesLow hnsw_ef, cold indexPerformance issues
Container exits immediatelyConfig error, missing license fileStartup failures
High memory usageLarge number of vectors, high concurrency, indexing workload, insufficient RAMMemory issues
Data lost after restartNo persistent volume mountedData 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.
1

Confirm the container is running

docker ps | grep cortex
If the container is not listed, start it:
docker start <container-id>
2

Check the port binding

Verify port 50051 is exposed:
docker port <container-id>
Expected output: 50051/tcp -> 0.0.0.0:50051
3

Test connectivity from the host

nc -zv localhost 50051
If this fails, check for firewall rules or other processes using the port:
lsof -i :50051
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:50051")  # 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.
CheckAction
Collection is emptyRun client.get_collection_info(name) and check points_count
Query vector has wrong dimensionsConfirm dimensions match collection.vectors_config.size
Filter is too restrictiveRemove the filter and retry to isolate the issue
Collection is still indexingCheck 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:50051") as client:
    info = client.get_collection_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.
hnsw_ef controls how many candidates the HNSW graph explores during search. Increase it to trade speed for better recall:
results = client.search(
    collection_name="my-collection",
    query_vector=query_embedding,
    limit=10,
    search_params={"hnsw_ef": 128}   # Override server default
)
Verify that the collection’s distance metric matches the one used to train your embedding model:
info = client.get_collection_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.
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.
CauseSolution
High hnsw_ef_constructionReduce to 100 for bulk loads; increase after
Inserting points one by oneBatch inserts — use lists of 100–1000 points per call
Insufficient memoryIncrease container memory limit

​
Slow queries

The following table lists common causes of slow queries and recommended solutions.
CauseSolution
High hnsw_efLower to 64 for faster queries at slightly lower recall
Cold start after restartRun a few warm-up queries before benchmarking
Payload filters on large collectionsCreate 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 messageCauseFix
failed to load configMalformed config.yamlValidate YAML syntax
license file not foundWrong VECTORAI_LICENSE_FILE pathCheck volume mount path
address already in usePort 50051 taken by another processStop the other process or change the port
permission denied: data_dirData directory not writableFix 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 -v /path/to/host/data:/app/data actian/cortex-server:latest

# Incorrect — data lost on container removal
docker run actian/cortex-server:latest
Verify the volume mount: 
docker inspect <container-id> | grep -A 10 Mounts

​
Next steps

Explore these related guides to learn more.

Monitoring and logging

Set up Prometheus metrics and alerts to catch issues early.

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.