Troubleshooting¶

Common issues and solutions.

Quick Diagnosis¶

Health Check¶

First, check system health:

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy",
  "checks": {
    "database": "ok",
    "vector_store": "ok",
    "llm_bridge": "ok"
  }
}

Component Status¶

# Controller
curl http://localhost:8080/health

# ChromaDB
curl http://localhost:8000/api/v1/heartbeat

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

Common Issues¶

Comprehensive troubleshooting guide:

Common Issues →

Connection errors
Database issues
Embedding generation failures
Performance problems
Memory issues

FAQ¶

Frequently asked questions:

FAQ →

General questions
Configuration
Performance
Integrations
Development

Debug Mode¶

Enable verbose logging:

# Set log level
export RUST_LOG=debug

# Or in config.toml
[logging]
level = "debug"

Performance Issues¶

If queries are slow:

Check Database Size
```
ls -lh data/sekha.db
```
Check ChromaDB
```
docker stats chroma
```
Monitor Resources
```
docker stats
```
Enable Query Logging
```
[logging]
sql_queries = true
```

Debugging Tips¶

Enable Detailed Logs¶

# Full debug output
export RUST_LOG=sekha=debug,sea_orm=debug

# Restart service
docker compose restart controller

Check Logs¶

# All logs
docker compose logs -f

# Specific service
docker compose logs -f controller
docker compose logs -f chroma
docker compose logs -f llm-bridge

Inspect Database¶

# Open SQLite
sqlite3 data/sekha.db

# Check tables
.tables

# Query conversations
SELECT COUNT(*) FROM conversations;

Getting Help¶

Community Support¶

Discord - Real-time help
GitHub Discussions - Q&A forum
GitHub Issues - Bug reports

Before Asking¶

Include:

System info: OS, Docker version
Logs: Relevant error messages
Config: Sanitized configuration
Steps: How to reproduce
Expected: What should happen
Actual: What actually happens

Next Steps¶

Common Issues - Detailed troubleshooting
FAQ - Quick answers
Configuration - Config reference
Deployment - Setup guide