Troubleshooting¶

Common issues and solutions when deploying Compere.

Common Issues¶

"No such table" Error¶

Symptom: Database table not found errors on startup.

Causes:

Models not imported in main.py
Database needs recreation
Database URL mismatch

Solutions:

# Delete and recreate SQLite database
rm compere.db
uv run compere

# For PostgreSQL, check connection string
echo $DATABASE_URL

Port Already in Use¶

Symptom: Address already in use error.

Solution:

# Find process using port
lsof -ti:8090

# Kill the process
lsof -ti:8090 | xargs kill -9

# Or use a different port
uv run compere --port 8091

CORS Errors¶

Symptom: Browser shows CORS errors, API calls fail.

Causes:

Frontend origin not in CORS_ORIGINS
CORS not configured at all
Reverse proxy stripping headers

Solutions:

# Set allowed origins
CORS_ORIGINS=http://localhost:3000,https://myapp.com

# For development, use wildcard
CORS_ORIGINS=*

Authentication Failures¶

Symptom: 401 Unauthorized errors.

Causes:

SECRET_KEY not set
Token expired
Wrong credentials

Solutions:

# Ensure SECRET_KEY is set
echo $SECRET_KEY

# Generate new secret
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Check auth is enabled
echo $AUTH_ENABLED

Database Connection Issues¶

Symptom: Connection refused or timeout errors.

Solutions:

# Test PostgreSQL connection
psql $DATABASE_URL -c "SELECT 1"

# Check Docker network (if using Docker)
docker-compose exec compere ping db

# Verify database exists
psql -h localhost -U postgres -l

Rate Limit Exceeded¶

Symptom: 429 Too Many Requests errors.

Solutions:

# Increase limit
RATE_LIMIT_REQUESTS=200
RATE_LIMIT_WINDOW=60

# Or disable temporarily
RATE_LIMIT_ENABLED=false

Memory Issues¶

Symptom: Container killed (OOMKilled) or slow performance.

Solutions:

# Check memory usage
docker stats

# Increase container memory
# In docker-compose.yml:
deploy:
  resources:
    limits:
      memory: 1G

Slow Queries¶

Symptom: API responses are slow.

Solutions:

Add database indexes (already included)
Enable connection pooling
Check query patterns

-- Check slow queries (PostgreSQL)
SELECT query, calls, mean_time
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

Debugging Tips¶

Enable Debug Logging¶

LOG_LEVEL=DEBUG

Check Container Logs¶

docker-compose logs -f compere

Test Endpoints¶

# Health check
curl http://localhost:8090/health

# Readiness check
curl http://localhost:8090/health/ready

# Create test entity
curl -X POST http://localhost:8090/entities/ \
  -H "Content-Type: application/json" \
  -d '{"name": "Test", "description": "Test entity", "image_urls": []}'

Database Inspection¶

# SQLite
sqlite3 compere.db ".tables"
sqlite3 compere.db "SELECT * FROM entities"

# PostgreSQL
docker-compose exec db psql -U compere -c "SELECT * FROM entities"

Getting Help¶

Check the GitHub Issues
Search existing issues before creating new ones
Include:
Compere version
Python version
Full error message
Steps to reproduce