> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vectoraidb.actian.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](#connection-issues) |
| `UNAVAILABLE` error from SDK | Server starting up, network blocked | [Connection issues](#connection-issues) |
| Search returns no results | Empty collection, wrong query vector dimensions | [Search issues](#search-issues) |
| Search results have poor quality | Low `hnsw_ef`, unoptimized index | [Search quality](#search-quality) |
| Slow ingestion | High `hnsw_ef_construction`, insufficient memory | [Performance issues](#performance-issues) |
| Slow queries | Low `hnsw_ef`, cold index | [Performance issues](#performance-issues) |
| Container exits immediately | Config error, missing license file | [Startup failures](#startup-failures) |
| High memory usage | Large number of vectors, high concurrency, indexing workload, insufficient RAM | [Memory issues](#memory-issues) |
| Data lost after restart | No persistent volume mounted | [Data persistence](#data-persistence) |
## Connection issues
### Server not reachable
```bash theme={null}
docker ps | grep vectorai
```
If the container is not listed, start it:
```bash theme={null}
docker start
```
Verify port `6574` is exposed:
```bash theme={null}
docker port
```
Expected output: `6574/tcp -> 0.0.0.0:6574`
```bash theme={null}
nc -zv localhost 6574
```
If this fails, check for firewall rules or other processes using the port:
```bash theme={null}
lsof -i :6574
```
```bash theme={null}
docker logs | 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`:
```python theme={null}
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
```python theme={null}
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
`hnsw_ef` controls how many candidates the HNSW graph explores during search. Increase it to trade speed for better recall:
```python theme={null}
from actian_vectorai import SearchParams
results = client.points.search(
"my-collection",
vector=query_embedding,
limit=10,
params=SearchParams(hnsw_ef=128) # Override server default
)
```
Verify that the collection's distance metric matches the one used to train your embedding model:
```python theme={null}
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.
Cosine similarity requires unit-normalized vectors. If your embedding model does not normalize by default, normalize before inserting and before querying:
```python theme={null}
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
```bash theme={null}
docker logs
```
| 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)
```bash theme={null}
docker logs | 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](/docs/fundamentals/indexing/indexing).
## 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:
```bash theme={null}
# 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:
```bash theme={null}
docker inspect | grep -A 10 Mounts
```
## Next steps
Handle specific gRPC error codes in your application code.
Container setup, volume mounts, and Docker Compose configuration.
Configure index parameters that affect search quality and performance.