UnifyRoute Logo UnifyRoute

Contact Us

Troubleshooting

Common issues and solutions for UnifyRoute

Table of Contents

Common Issues & Solutions

Installation & Setup

Python Version Error

Error: Python 3.11+ required

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# Check Python version
python --version
python3.11 --version

# On Ubuntu/Debian
sudo apt-get install python3.11 python3.11-venv

# On macOS with Homebrew
brew install python@3.11

# Set alias if needed
alias python=python3.11

# Or use virtual environment
python3.11 -m venv venv
source venv/bin/activate

Redis Connection Error

Error: Cannot connect to Redis at localhost:6379

Solutions:

  1. Redis not installed:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# On macOS
brew install redis
brew services start redis

# On Linux
sudo apt-get install redis-server
sudo systemctl start redis-server

# On Docker
docker run -d -p 6379:6379 redis:7-alpine
  1. Redis on different host:
1
2

# Update .env
REDIS_URL=redis://your-redis-host:6379
  1. Use memory cache for development:
1
2

# In .env
REDIS_URL=memory://

Server & Gateway

Port Already in Use

Error: Address already in use :6565

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Find process using port
lsof -i :6565
# or on Windows
netstat -ano | findstr :6565

# Kill process
kill -9 PID
# or on Windows
taskkill /PID PID /F

# Or use different port
SERVER_PORT=6566 ./unifyroute start

Server Not Starting

Error: Failed to start server

Steps to debug:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 1. Check logs
tail -f logs/unifyroute.log

# 2. Verify configuration
./unifyroute config validate

# 3. Check database
sqlite3 unifyroute.db ".tables"

# 4. Run with debug mode
DEBUG=true ./unifyroute start

Database Issues

Database Lock

Error: database is locked

Solution:

1
2
3
4
5
6
7
8
9

# 1. Remove lock files
rm unifyroute.db-wal
rm unifyroute.db-shm

# 2. Check if process has hold
lsof unifyroute.db

# 3. Reinitialize
./unifyroute setup

Database Version Mismatch

Error: Database schema version mismatch

Solution:

1
2
3
4
5
6
7
8

# 1. Backup current database
cp unifyroute.db unifyroute.db.backup

# 2. Run migrations
./unifyroute migration migrate

# 3. If migration fails, restore
mv unifyroute.db.backup unifyroute.db

Providers & Credentials

Provider Authentication Error

Error: Invalid API key for provider OpenAI

Solutions:

  1. Check API key:
1
2

# Verify key format matches provider requirements
./unifyroute providers test openai
  1. Check provider credentials in dashboard:
  • Navigate to Providers
  • Click Edit on the provider
  • Re-enter API credentials
  • Test connection
  1. Check environment variables:
1
2

# Make sure credentials are in .env
echo $OPENAI_API_KEY

Provider Not Found in Routing

Error: Provider 'openai' not found in routing configuration

Solution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 1. List configured providers
./unifyroute providers list

# 2. Add provider if missing
./unifyroute providers add \
  --name openai \
  --type openai \
  --api-key sk-...

# 3. Update routing configuration
./unifyroute config show routing
./unifyroute config edit

Quota Exceeded Error

Error: Provider quota exceeded

Solutions:

  1. Check current quota:
1

./unifyroute stats --by provider
  1. Reset quota in dashboard:
  • Go to “Providers”
  • Click provider
  • Update quota limit
  • Save
  1. Monitor usage:
1

./unifyroute logs --service quota --follow

API & Requests

Authentication Failed

Error: 401 Unauthorized - Invalid token

Solutions:

  1. Verify token exists:
1

./unifyroute tokens list
  1. Check token header format:
1
2

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:6565/api/v1/models
  1. Verify token permissions:
1

./unifyroute tokens info YOUR_TOKEN
  1. Create new token if expired:
1

./unifyroute tokens create --name "new-token"

Rate Limit Exceeded

Error: 429 Too Many Requests

Solutions:

  1. Check rate limits:
1

./unifyroute tokens info YOUR_TOKEN
  1. Reduce request rate:
1
2
3

# On client side: add delays between requests
import time
time.sleep(1)  # Wait 1 second between requests
  1. Increase rate limit:
1
2

./unifyroute tokens modify YOUR_TOKEN \
  --rate-limit 200  # requests/minute

Model Not Found

Error: Model 'gpt-4' not found

Solutions:

  1. List available models:
1
2

curl http://localhost:6565/api/v1/models \
  -H "Authorization: Bearer YOUR_TOKEN"
  1. Check provider has model:
1

./unifyroute providers test openai
  1. Add model to provider config:
1
2
3
4
5
6

# In config.yaml
providers:
  openai:
    models:
      - gpt-4      # Add this
      - gpt-3.5-turbo

Performance Issues

Slow Response Times

Debugging:

  1. Check provider response:
1
2
3
4

time curl -X POST http://localhost:6565/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"hi"}]}'
  1. Check server load:
1
2
3

./unifyroute stats  # View statistics
top                 # Check CPU/memory
redis-cli info      # Check Redis
  1. Increase workers:
1

SERVER_WORKERS=8 ./unifyroute start

High Memory Usage

Solutions:

  1. Reduce cache TTL:
1
2
3
4
5

# In config.yaml
cache:
  ttl:
    credentials: 1800  # Reduce from 3600
    quota: 900         # Reduce from 1800
  1. Limit database pool:
1
2
3

database:
  postgresql:
    pool_size: 10   # Reduce from 20
  1. Clear old logs:
1

rm logs/*.log.* # Remove rotated logs

High CPU Usage

Solutions:

  1. Check logs for errors:
1

tail -f logs/unifyroute.log | grep ERROR
  1. Reduce polling frequency:
1
2
3
4

# In config.yaml
quota:
  monitoring:
    poll_interval: 7200  # Increase from 3600
  1. Restart services:
1

./unifyroute restart

Logging & Debugging

Enable Debug Logging

1
2
3
4
5
6

# Set environment variable
DEBUG=true ./unifyroute start

# Or in .env
DEBUG=true
LOG_LEVEL=DEBUG

View Logs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Follow API logs
./unifyroute logs --service api --follow

# View all logs since 1 hour ago
./unifyroute logs --since 1h

# Get logs for specific error
./unifyroute logs | grep "ERROR"

# Export logs to file
./unifyroute logs > logs_export.txt

Enable Request Tracing

1
2
3
4
5
6
7

# In config.yaml
logging:
  level: DEBUG
  components:
    api: DEBUG
    router: DEBUG
    provider: DEBUG

Each request will have a correlation ID in logs.

Health & Diagnostics

System Health Check

1
2
3
4
5
6
7

# Full health check
./unifyroute health

# Specific checks
./unifyroute health --check database
./unifyroute health --check redis
./unifyroute health --check providers

Database Integrity

1
2
3
4
5

# Check database
sqlite3 unifyroute.db "PRAGMA integrity_check;"

# Vacuum to optimize
sqlite3 unifyroute.db "VACUUM;"

Provider Status

1
2
3
4
5

# Test all providers
./unifyroute providers test

# Detailed provider status
./unifyroute providers list --format json

Getting Help

Report Issues

  1. Check existing issues: https://github.com/unifyroute/UnifyRoute/issues

  2. Create new issue with:

    • Error message (full traceback)
    • Steps to reproduce
    • UnifyRoute version
    • Configuration details (API keys redacted)
    • Logs

Enable Detailed Logging

When reporting issues, include:

1
2
3
4
5
6

# Collect diagnostic info
./unifyroute health > diagnostics.txt
./unifyroute config show >> diagnostics.txt
./unifyroute logs --since 24h >> diagnostics.txt

# Share diagnostics (remove sensitive data)

Community Support

Last updated: January 1, 0001