Troubleshooting¶

Common issues and solutions when using RavenRustRAG.

Ollama Connection Errors¶

"Failed to connect to Ollama"¶

Symptoms: Indexing or querying fails with a connection error.

Solutions:

Verify Ollama is running:
```
curl http://localhost:11434/api/tags
```
Start Ollama if not running:
```
OLLAMA_NO_CLOUD=1 ollama serve
```

If using a non-default URL, pass --url:

ravenrag query "test" --url http://my-host:11434

Run diagnostics:
```
ravenrag doctor
```

"Model not found"¶

Symptoms: Embedding fails with a model error.

Solutions:

Pull the model:

OLLAMA_NO_CLOUD=1 ollama pull nomic-embed-text

Verify it's available:
```
ollama list
```

If using a different model, specify it:

ravenrag index ./docs --model mxbai-embed-large

Database Errors¶

"Database is locked"¶

Symptoms: Operations fail with SQLite busy/locked errors.

Solutions:

This usually resolves within 5 seconds (busy_timeout). If persistent:

Check for zombie processes holding the lock:

fuser raven.db  # Linux
lsof raven.db   # macOS

Remove stale WAL files (only if no process is using the DB):
```
rm raven.db-wal raven.db-shm
```

"Dimension mismatch"¶

Symptoms: Query fails because the embedding dimension doesn't match stored vectors.

Cause: You indexed with one model (e.g., 768-dim nomic-embed-text) but are querying with a different model (e.g., 1536-dim text-embedding-3-small).

Solution: Use the same model for indexing and querying, or clear and re-index:

ravenrag clear
ravenrag index ./docs --model nomic-embed-text
ravenrag query "test" --model nomic-embed-text

Indexing Issues¶

"No documents found"¶

Symptoms: ravenrag index reports 0 documents.

Solutions:

Check file extensions match. Default is txt,md:

ravenrag index ./docs --extensions md,txt,html,json

Verify the path contains files:

find ./docs -type f \( -name "*.md" -o -name "*.txt" \)

"Duplicate indexing / growing database"¶

Symptoms: Database grows on every re-index even without content changes.

Solution: RavenRustRAG uses fingerprinting for incremental indexing. If your files haven't changed, re-indexing should be a no-op. If the database grows unexpectedly:

Check if file modification times are changing (backups, syncing tools)

Clear and re-index from scratch:

ravenrag clear && ravenrag index ./docs

Server Issues¶

"Address already in use"¶

Symptoms: ravenrag serve fails to bind.

Solutions:

Use a different port:
```
ravenrag serve --port 8485
```
Find and kill the existing process:
```
lsof -i :8484
kill <PID>
```

"401 Unauthorized"¶

Symptoms: API calls return 401.

Solution: Include the Bearer token:

curl -H "Authorization: Bearer $RAVEN_API_KEY" http://localhost:8484/query \
  -d '{"query": "test"}'

Performance Issues¶

Slow Indexing¶

Check Ollama is running on the same machine (network latency)
Consider a faster model (nomic-embed-text is fast; larger models are slower)
Reduce chunk overlap to generate fewer chunks
Use SSD storage for the database

Slow Queries¶

Check database size — very large indexes benefit from mmap (enabled by default)
Reduce top_k if you don't need many results
Avoid hybrid search if BM25 isn't needed for your use case
Run ravenrag benchmark to baseline your system

Docker Issues¶

"Permission denied" on volume¶

Symptoms: Container can't write to mounted volume.

Solution: The container runs as UID 65534. Ensure the host directory is writable:

chmod 777 ./data  # or chown to 65534
docker run -v ./data:/data ghcr.io/egkristi/ravenrustrag:latest info --db /data/raven.db

Container can't reach Ollama¶

Solution: Use host networking or the host's IP:

# Linux
docker run --network host ghcr.io/egkristi/ravenrustrag:latest \
  query "test" --url http://localhost:11434

# macOS/Windows (Docker Desktop)
docker run ghcr.io/egkristi/ravenrustrag:latest \
  query "test" --url http://host.docker.internal:11434

Getting Help¶

Run ravenrag doctor for automated diagnostics
Use --verbose flag for detailed logging
Use --json for machine-parseable output
Check GitHub Issues