Troubleshooting

Common issues and solutions for th0th deployment and operation

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:3333

Solution:

1. Check what’s using port 3333:

   # Linux/Mac
   lsof -i :3333
   
   # Or using netstat
   netstat -tulpn | grep 3333
   

2. Either stop the conflicting service or change th0th’s port:

   export TH0TH_API_PORT=3334
   bun run start:api
   

3. For Docker:

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

Environment variables not loaded

Symptom: API uses default values instead of .env configuration

Solution:

1. Verify .env file location (must be at project root):

   ls -la .env
   

2. Check file permissions:

   chmod 644 .env
   

3. For Docker, ensure environment is passed:

   services:
     api:
       env_file:
         - .env
   

4. 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 files

Solution:

1. Ensure data directory exists and is writable:

   mkdir -p ~/.rlm
   chmod 755 ~/.rlm
   

2. For Docker, check volume permissions:

   docker volume inspect th0th-data
   

3. 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 responding

Solutions:

1. Verify Ollama is running

   # Check if Ollama is running
   curl http://localhost:11434/api/tags
   
   # If not running, start it
   ollama serve
   
2. Check the correct URL

   # Test with your configured URL
   curl ${OLLAMA_BASE_URL}/api/tags
   
3. 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
   
4. 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 found

Solution:

1. List available models:

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

2. Pull the required model:

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

3. Update .env to match available model:

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

4. Restart th0th:

   docker compose restart api
   

Slow embedding generation

Symptom: Indexing or search operations take too long

Performance tuning:

1. Use GPU acceleration (if available):

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

2. Switch to smaller model:

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

3. Enable embedding cache:

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

4. 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 1

Diagnosis:

# View container logs
docker compose logs api

# View last run logs
docker logs th0th-api

Common causes:

1. Missing Ollama connection: Ensure OLLAMA_BASE_URL points to accessible Ollama instance
2. Permission errors: Check volume mount permissions
3. 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 ps

Diagnosis:

# 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:

1. Increase start period (for slow systems):

   healthcheck:
     start_period: 60s  # Default: 40s
   

2. Check if API is actually running:

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

3. View API logs:

   docker compose logs -f api
   

Volume data not persisting

Symptom: Indexed projects disappear after container restart

Solution:

1. Verify volume is mounted:

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

2. Check volume exists:

   docker volume ls | grep th0th
   

3. Inspect volume location:

   docker volume inspect th0th-data
   

4. 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 content

Diagnosis:

1. Check if project is indexed:

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

2. 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:

1. 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"
     }'
   

2. 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 hours

Solutions:

1. Check available disk space:

   df -h
   

2. Exclude large directories:

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

3. Increase memory limits (Docker):

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

4. Monitor progress:

   # Watch logs during indexing
   docker compose logs -f api
   

Cache not working

Symptom: Every search takes same time, no cache hits

Diagnosis:

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

Solutions:

1. Verify cache configuration:

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

2. Check cache database:

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

3. 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:

1. Reduce cache sizes:

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

2. Restart service periodically (clears in-memory cache):

   docker compose restart api
   

3. 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 slowly

Performance checklist:

1. Check Ollama latency

   curl http://localhost:3333/api/v1/system/ollama
   # Check 'latency' field (should be < 100ms)
   
2. 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
   
3. Check database sizes

   curl http://localhost:3333/api/v1/system/info
   # Large databases (> 5GB) may slow down queries
   
4. 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 effect

Solution:

1. Restart the service (required for changes to apply):

   docker compose restart api
   

2. Verify variables are loaded:

   docker compose exec api env | grep OLLAMA
   

3. 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 applied

Note:

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 results

Recovery:

# 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 errors

Solutions:

1. Check database sizes:

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

2. Clear old caches:

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

3. Reduce cache limits:

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

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

Getting Help

If you’re still experiencing issues:

1. 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
   
2. Check existing issues

   Search the GitHub issues for similar problems

3. 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

Next Steps

Deployment

Review deployment configuration

Monitoring

Set up monitoring and health checks