Docker Compose "env file not found" - Fix Missing env_file in CI

Compose was told to load environment values from a file that does not exist on the runner. In CI the file is often gitignored and never created.

What this error means

docker compose up/config fails immediately with env file <path> not found. Locally it works because the file exists on your machine; in CI it was never checked out or generated.

docker compose output

env file /home/runner/work/app/app/.env not found:
stat /home/runner/work/app/app/.env: no such file or directory

Common causes

The env file is gitignored and not created in CI

A .env referenced by env_file: is excluded from the repo, so on a fresh CI checkout it simply does not exist.

Wrong relative path

The env_file path is resolved relative to the compose file’s directory; running compose from a different working directory points at the wrong location.

How to fix it

Create the env file in the job

Write the file from CI secrets/variables before running compose.

.github/workflows/test.yml

cat > .env <<'EOF'
DATABASE_URL=${{ secrets.DATABASE_URL }}
API_KEY=${{ secrets.API_KEY }}
EOF
docker compose up -d

Make env_file optional or fix the path

Newer Compose supports marking an env file optional, or correct the relative path.

docker-compose.yml

services:
  api:
    env_file:
      - path: .env
        required: false

How to prevent it

Generate .env from CI secrets as an explicit step.
Commit a .env.example and create the real file in CI from it.
Run compose from the directory the env_file paths assume.