#Troubleshooting

Common issues and how to fix them.

#Docker & connection issues

#"Connection refused" or "Cannot connect to database"

Cause: .env is missing, or DATABASE_URL uses localhost instead of Docker service names.

Fix: Make sure DATABASE_URL points to postgres (the Docker service name), not localhost:

DATABASE_URL=postgresql+psycopg://eval752:password@postgres:5432/eval752

Then restart:

docker compose down && docker compose up -d

#"ENCRYPTION_KEY not set"

Fix: Generate a key and add it to .env:

openssl rand -hex 32
# Paste the output into ENCRYPTION_KEY in .env
docker compose restart backend

#Volume conflicts after updating

If you see database authentication errors after pulling new code, your existing Docker volumes probably don't match the current .env.

docker compose down -v    # ⚠️ Deletes all stored data
docker compose up --build -d

#Provider issues

#Smoke test fails

Use the error code to narrow it down:

#Smoke test breaks after changing ENCRYPTION_KEY

Your database has provider secrets encrypted with the old key. For a disposable local workspace:

docker compose down -v
docker compose up -d

Then re-add your provider. If you need to keep old records, restore the original ENCRYPTION_KEY instead.

#Dataset issues

#Import fails

Common causes:

• Wrong Hugging Face dataset path — copy the exact path from HF Datasets
• Private dataset without HF_TOKEN set in .env
• Preview timing out on a large dataset — start with test[:30]

#Run issues

#Run stuck in "Pending"

The worker might be down or can't reach Redis/PostgreSQL.

docker compose ps celery-worker        # Is it running?
docker compose logs -f celery-worker   # Any errors?
docker compose restart celery-worker   # Try restarting

If still stuck, also check backend and redis logs.

For the complete first-run walkthrough, see the Quick Start.