Docker Compose "env file ... not found" in CI

Compose could not find a referenced env file. env file <path> not found means an env_file: entry (or --env-file) points at a path that does not exist relative to where Compose resolves it - commonly a gitignored .env or a wrong relative path in CI.

What this error means

A docker compose up/config fails with env file /path/to/.env not found or env_file: <name> not found. The file exists locally but is absent in the CI checkout, or the path is wrong.

docker

env file /home/runner/work/app/app/config/prod.env not found
# env_file: ./config/prod.env  - the file is gitignored, so it is not in the CI checkout

Common causes

The env file is gitignored / not in the checkout

A .env/*.env excluded from version control is not present on the CI runner, so the referenced path does not exist.

A wrong relative path

env_file paths resolve relative to the compose file (or working directory); a mismatched relative path points at nothing.

--env-file pointing at a missing file

A CLI --env-file <path> that does not exist on the runner fails before services start.

How to fix it

Provide the env file in CI

Generate the env file from secrets at the start of the job, or commit a non-secret template.

.github/workflows/ci.yml

printf 'API_KEY=%s\nDB_HOST=%s\n' "${{ secrets.API_KEY }}" "$DB_HOST" > config/prod.env
docker compose --env-file config/prod.env up -d

Fix the path or make env_file optional

Correct the relative path, or mark optional env files so a missing one is not fatal (recent Compose).

docker-compose.yml

services:
  api:
    env_file:
      - path: ./config/prod.env
        required: false

How to prevent it

Generate secret env files from CI secrets at job start.
Use paths relative to the compose file and verify they exist.
Mark optional env files required: false where supported.