troubleshooting.md

Troubleshooting Guide

Common issues and their solutions for AIDEN.

Connection Issues

Ollama Connection Failed

Symptom

Error: connection refused
Caused by: Connection refused (os error 111)

Solution

1. Ensure Ollama is installed:

   curl -fsSL https://ollama.com/install.sh | sh

2. Start Ollama service:

   ollama serve

3. Verify it's running:

   curl http://localhost:11434/api/version

4. Pull required models:

   ollama pull llama3.2:1b
   ollama pull nomic-embed-text

---

Qdrant Connection Failed

Symptom

Error: Connection refused to Qdrant at localhost:6334

Solution

1. Start Qdrant with Docker:

   docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

2. Verify it's running:

   curl http://localhost:6333/readyz

3. For persistent storage:

   docker run -p 6333:6333 -p 6334:6334 \
     -v qdrant_data:/qdrant/storage \
     qdrant/qdrant

---

Model Issues

Model Not Found

Symptom

Error: model 'llama3.2:1b' not found

Solution

ollama pull llama3.2:1b
ollama pull nomic-embed-text

List available models:

ollama list

---

Out of Memory

Symptom

Error: CUDA out of memory

Solution

1. Use a smaller model:

   // In src/state.rs
   chat_model: "llama3.2:1b".to_string(),  // Smaller model

2. Close other applications using GPU

3. Check GPU memory:

   nvidia-smi

---

Indexing Issues

No Documents Found

Symptom

Files processed: 0

Solution

1. Create docs directory:

   mkdir -p docs

2. Add markdown files:

   echo "# My Doc" > docs/README.md

3. Verify files exist:

   ls -la docs/
   find docs/ -name "*.md"

---

Indexing Stuck

Symptom

Indexing status never completes

Solution

1. Check logs:

   journalctl -u aiden -f

2. Restart service:

   sudo systemctl restart aiden

3. Clear Qdrant collection and re-index:

   curl -X DELETE http://localhost:6333/collections/aiden

---

Poor Search Results

Symptom

Responses don't match documentation

Solution

1. Check threshold (try lowering):

   // In src/state.rs
   threshold: 0.5,  // Lower threshold

2. Increase max results:

   max_results: 10,  // More context

3. Re-index with larger chunks:

   chunk_size: 768,  // Larger chunks

---

Web Interface Issues

Page Won't Load

Symptom

404 Not Found

Solution

1. Check server is running:

   curl http://localhost:8081/

2. Verify firewall:

   sudo ufw allow 8081

3. Check logs:

   sudo journalctl -u aiden -n 50

---

WebSocket Connection Failed

Symptom

WebSocket connection failed

Solution

1. Check reverse proxy WebSocket support:

   # Nginx location block
   proxy_http_version 1.1;
   proxy_set_header Upgrade $http_upgrade;
   proxy_set_header Connection "upgrade";

2. Test WebSocket directly:

   wscat -c ws://localhost:8081/api/chat/stream

---

Build Issues

Compilation Errors

Symptom

error: cannot find crate 'axum'

Solution

cargo update
cargo build

---

Missing OpenSSL

Symptom

error: unable to find the openssl development headers

Solution

# Debian/Ubuntu
sudo apt install libssl-dev pkg-config

# Arch Linux
sudo pacman -S openssl pkg-config

# Fedora
sudo dnf install openssl-devel pkg-config

---

Performance Issues

Slow Responses

Possible Causes

• Large model running on CPU
• Many documents to search
• Network latency to Ollama

Solutions

1. Use smaller model:

   chat_model: "llama3.2:1b".to_string(),
   embed_model: "nomic-embed-text".to_string(),

2. Reduce max results:

   max_results: 3,

3. Use GPU for Ollama:

   OLLAMA_HOST=cuda:11434 ollama serve

---

Health Check Issues

Health Check Shows Degraded

Solution

1. Run health check manually:

   curl http://localhost:8081/api/health

2. Check Ollama:

   curl http://localhost:11434/api/tags

3. Check Qdrant:

   curl http://localhost:6333/collections

---

Getting Help

If issues persist:

1. Check logs:

   RUST_LOG=debug ./target/release/aiden

2. Open an issue on GitLab/GitHub with:

   • AIDEN version (./aiden --version or check Cargo.toml)
   • Full error message
   • Steps to reproduce
   • System information (uname -a)