Common CI Failures Reference

1. Database Readiness Race Condition

• Symptom: ConnectionRefusedError: [Errno 111]
• Root Cause: Web application container starts before PostgreSQL is ready to accept connections.
• Fix: Use Docker Compose condition: service_healthy or an explicit wait loop (pg_isready).

2. Missing Environment Variables

• Symptom: KeyError: 'DATABASE_URL'
• Root Cause: Environment variable specified in .env is omitted in CI workflow file (.github/workflows/ci.yml).
• Fix: Declare default fallback in configuration or pass test env vars in CI step.

3. Unapplied Database Migrations

• Symptom: UndefinedTable: relation "users" does not exist
• Root Cause: CI runner did not execute migration command prior to test execution.
• Fix: Add migration target (docker compose run --rm backend alembic upgrade head) to CI pipeline.