Troubleshooting

Quick Diagnostics

Run the comprehensive health check to identify issues:

curl http://localhost:3333/api/v1/system/health/local

The response includes specific recommendations for any detected problems.

Common Issues

API Not Starting

Port already in use

Symptom: Error message EADDRINUSE: address already in use ::1:3333Solution:

Check what’s using port 3333:

# Linux/Mac
lsof -i :3333

# Or using netstat
netstat -tulpn | grep 3333

Either stop the conflicting service or change th0th’s port:
```
export TH0TH_API_PORT=3334
bun run start:api
```

For Docker:

# docker-compose.yml
ports:
  - "3334:3333"

Environment variables not loaded

Symptom: API uses default values instead of .env configurationSolution:

Verify .env file location (must be at project root):
```
ls -la .env
```
Check file permissions:
```
chmod 644 .env
```

For Docker, ensure environment is passed:

services:
  api:
    env_file:
      - .env

Restart the service after changes:

# Docker
docker compose restart api

# Source
# Stop with Ctrl+C and restart
bun run start:api

Database initialization errors

Symptom: Errors about missing or locked database filesSolution:

Ensure data directory exists and is writable:
```
mkdir -p ~/.rlm
chmod 755 ~/.rlm
```
For Docker, check volume permissions:
```
docker volume inspect th0th-data
```

Clear corrupted databases (⚠️ DELETES ALL DATA):

# Docker
docker compose down -v
docker compose up -d

# Source
rm -rf ~/.rlm/*.db
bun run start:api

Ollama Connection Issues

Ollama not responding

Symptom: Health check shows Ollama is not respondingSolutions:

Verify Ollama is running

# Check if Ollama is running
curl http://localhost:11434/api/tags

# If not running, start it
ollama serve

Check the correct URL

# Test with your configured URL
curl ${OLLAMA_BASE_URL}/api/tags

WSL/Docker: Use host.docker.internal

If Ollama is on Windows host and th0th in WSL/Docker:

# .env
OLLAMA_BASE_URL=http://host.docker.internal:11434

Remote Ollama: Update base URL

# .env
OLLAMA_BASE_URL=http://192.168.1.100:11434

Embedding model not found

Symptom: Error model 'nomic-embed-text' not foundSolution:

List available models:

ollama list
# Or via API
curl http://localhost:11434/api/tags

Pull the required model:

ollama pull nomic-embed-text:latest
# Or alternative
ollama pull bge-m3

Update .env to match available model:

OLLAMA_EMBEDDING_MODEL=nomic-embed-text:latest
OLLAMA_EMBEDDING_DIMENSIONS=768

Restart th0th:
```
docker compose restart api
```

Slow embedding generation

Symptom: Indexing or search operations take too longPerformance tuning:

Use GPU acceleration (if available):

# Install CUDA support for Ollama
# See: https://ollama.com/download

Switch to smaller model:

OLLAMA_EMBEDDING_MODEL=nomic-embed-text:latest
OLLAMA_EMBEDDING_DIMENSIONS=768

Enable embedding cache:

# .env
EMBEDDING_CACHE_DB_PATH=./data/embedding-cache.db

Increase Ollama concurrency:

# Set before starting Ollama
export OLLAMA_NUM_PARALLEL=4
ollama serve

Docker Issues

Container exits immediately

Symptom: docker compose up shows container exiting with code 0 or 1Diagnosis:

# View container logs
docker compose logs api

# View last run logs
docker logs th0th-api

Common causes:

Missing Ollama connection: Ensure OLLAMA_BASE_URL points to accessible Ollama instance
Permission errors: Check volume mount permissions
Port conflict: Another service using port 3333

Solution:

# Fix and rebuild
docker compose down
docker compose build --no-cache
docker compose up -d

Health check failing

Symptom: Container shows as unhealthy in docker psDiagnosis:

# Check health status
docker inspect th0th-api --format='{{json .State.Health}}' | jq

# View health check logs
docker inspect th0th-api | grep -A 30 Health

Solutions:

Increase start period (for slow systems):

healthcheck:
  start_period: 60s  # Default: 40s

Check if API is actually running:

docker compose exec api curl -f http://localhost:3333/health

View API logs:
```
docker compose logs -f api
```

Volume data not persisting

Symptom: Indexed projects disappear after container restartSolution:

Verify volume is mounted:

docker compose config
# Check for 'th0th-data:/data' under volumes

Check volume exists:
```
docker volume ls | grep th0th
```
Inspect volume location:
```
docker volume inspect th0th-data
```

Ensure using named volume (not bind mount):

# docker-compose.yml
volumes:
  - th0th-data:/data  # ✓ Named volume
  # NOT: ./data:/data  # ✗ Bind mount

volumes:
  th0th-data:
    driver: local

Search and Indexing Issues

Search returns no results

Symptom: Search endpoint returns empty results for known contentDiagnosis:

Check if project is indexed:

curl http://localhost:3333/api/v1/system/info
# Check databases.sizes for non-zero vector-store.db

Verify project ID:

curl -X POST http://localhost:3333/api/v1/search/project \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "projectId": "your-project-id"}'

Solutions:

Re-index the project:

curl -X POST http://localhost:3333/api/v1/project/index \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "/path/to/project",
    "projectId": "my-project"
  }'

Check embedding cache:

# View cache analytics
curl -X POST http://localhost:3333/api/v1/analytics \
  -H "Content-Type: application/json" \
  -d '{"type": "cache"}'

Indexing fails or is very slow

Symptom: Project indexing times out or takes hoursSolutions:

Check available disk space:
```
df -h
```

Exclude large directories:

# Use .gitignore patterns
# th0th respects .gitignore automatically
echo "node_modules/" >> .gitignore
echo "dist/" >> .gitignore
echo "*.log" >> .gitignore

Increase memory limits (Docker):

services:
  api:
    mem_limit: 4g
    memswap_limit: 4g

Monitor progress:

# Watch logs during indexing
docker compose logs -f api

Cache not working

Symptom: Every search takes same time, no cache hitsDiagnosis:

curl -X POST http://localhost:3333/api/v1/analytics \
  -H "Content-Type: application/json" \
  -d '{"type": "cache"}'

Solutions:

Verify cache configuration:

# .env
L1_CACHE_MAX_SIZE=104857600
L1_CACHE_TTL=300
L2_CACHE_MAX_SIZE=524288000
L2_CACHE_TTL=3600

Check cache database:

ls -lh ~/.rlm/search-cache.db
# Or for Docker
docker compose exec api ls -lh /data/search-cache.db

Clear corrupted cache:

rm ~/.rlm/search-cache.db
# Restart API to recreate

Memory and Performance

High memory usage

Symptom: Process using excessive RAM (> 2GB)Diagnosis:

curl http://localhost:3333/api/v1/system/info
# Check memory.process.rss

Solutions:

Reduce cache sizes:

# .env
L1_CACHE_MAX_SIZE=52428800   # 50MB
L2_CACHE_MAX_SIZE=262144000  # 250MB

Restart service periodically (clears in-memory cache):
```
docker compose restart api
```

Set Node.js memory limits:

# For source deployment
NODE_OPTIONS="--max-old-space-size=1024" bun run start:api

Slow API responses

Symptom: API endpoints timeout or respond slowlyPerformance checklist:

Check Ollama latency

curl http://localhost:3333/api/v1/system/ollama
# Check 'latency' field (should be < 100ms)

Verify cache hit rate

curl -X POST http://localhost:3333/api/v1/analytics \
  -H "Content-Type: application/json" \
  -d '{"type": "cache"}'
# Target: > 60% hit rate

Check database sizes

curl http://localhost:3333/api/v1/system/info
# Large databases (> 5GB) may slow down queries

Monitor system resources

# Docker
docker stats th0th-api

# Source
top -p $(pgrep -f th0th)

Configuration Issues

Environment variables not applied

Symptom: Changes to .env file not taking effectSolution:

Restart the service (required for changes to apply):
```
docker compose restart api
```

Verify variables are loaded:

docker compose exec api env | grep OLLAMA

For source deployment, ensure .env is in correct location:

# .env must be at project root
/path/to/th0th/.env  # ✓
/path/to/th0th/apps/tools-api/.env  # ✗

Config file ignored

Symptom: ~/.config/th0th/config.json changes not appliedNote:

The config file is primarily used by the MCP client. The API uses environment variables from .env.

For API configuration, use .env file:

# API uses .env
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_EMBEDDING_MODEL=bge-m3

For MCP client, use config file:

npx @th0th-ai/mcp-client --config-show

Data and Database Issues

Database corruption

Symptom: SQLite errors, crashes, or inconsistent resultsRecovery:

# 1. Backup existing databases
cp -r ~/.rlm ~/.rlm.backup

# 2. Try to repair with SQLite
sqlite3 ~/.rlm/vector-store.db "PRAGMA integrity_check;"

# 3. If corrupted, restore from backup or recreate
rm ~/.rlm/vector-store.db
# Re-index projects

# 4. For Docker volumes
docker run --rm -v th0th-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/th0th-backup-$(date +%Y%m%d).tar.gz /data

Disk space issues

Symptom: Out of disk space errorsSolutions:

Check database sizes:

curl http://localhost:3333/api/v1/system/info
# Check databases.total

Clear old caches:

rm ~/.rlm/search-cache.db
rm ~/.rlm/embedding-cache.db

Reduce cache limits:

# .env
L1_CACHE_MAX_SIZE=26214400   # 25MB
L2_CACHE_MAX_SIZE=104857600  # 100MB

Remove unused projects (requires manual database cleanup or full reset)

Getting Help

If you’re still experiencing issues:

Gather diagnostics

# Health check
curl http://localhost:3333/api/v1/system/health/local > health.json

# System info
curl http://localhost:3333/api/v1/system/info > info.json

# Logs
docker compose logs api > logs.txt

Check existing issues

Search the GitHub issues for similar problems

Create detailed issue

Include:

th0th version (docker image inspect th0th-api or package.json)
Deployment method (Docker/source)
Operating system and version
Ollama version (ollama --version)
Error messages and logs
Diagnostic outputs from Step 1

Get Started

Integration

Core Concepts

Configuration

Operations

Troubleshooting

Quick Diagnostics

Common Issues

API Not Starting

Ollama Connection Issues

Docker Issues

Search and Indexing Issues

Memory and Performance

Configuration Issues

Data and Database Issues

Getting Help

Next Steps

Deployment

Monitoring

Build docs developers (and LLMs) love

Get Started

Integration

Core Concepts

Configuration

Operations

Documentation Index

​Quick Diagnostics

​Common Issues

​API Not Starting

​Ollama Connection Issues

​Docker Issues

​Search and Indexing Issues

​Memory and Performance

​Configuration Issues

​Data and Database Issues

​Getting Help

​Next Steps

Deployment

Monitoring

Build docs developers (and LLMs) love

Quick Diagnostics

Common Issues

API Not Starting

Ollama Connection Issues

Docker Issues

Search and Indexing Issues

Memory and Performance

Configuration Issues

Data and Database Issues

Getting Help

Next Steps