🐳 Docker Error Guide: 'env file not found' in Docker Compose

Exact Error Message

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

You may also see the Compose V1 wording Couldn't find env file: /home/deploy/app/.env, the service-level form env file ./config/prod.env not found, or failed to read ... : no such file or directory. All of them mean Docker Compose was told to load an environment file that does not exist at the resolved path.

What It Means

Docker Compose reads environment variables from two distinct places. The top-level project .env file (used for variable substitution inside compose.yaml) is loaded from the directory that contains the Compose file, or from the path given by --env-file. Separately, each service can declare an env_file: key pointing at one or more files whose contents become that container’s environment.

The env file ... not found error means one of those referenced paths does not resolve to a real file. Compose does not silently ignore a missing env file; it stops with an error so you do not accidentally start a container with no configuration. The fix is almost always a path or working-directory mismatch.

Common Causes

• A .env file is expected but absent (never created, git-ignored, or not copied to the deploy host).
• env_file: uses a path relative to the Compose file, but you ran docker compose from a different directory than expected.
• --env-file prod.env was passed but the file lives elsewhere or is misspelled.
• The file exists but with the wrong name (.env.production vs .env, or a stray extension).
• A CI checkout excludes .env (correctly ignored) without providing a replacement.
• Windows/Unix path separators or a leading ./ were confused across environments.

Diagnostic Commands

Confirm which directory Compose treats as the project root and which env file it loads:

docker compose config

List the files actually present where Compose is looking:

ls -la
ls -la config/

Render the resolved configuration to see how variables and paths expand:

docker compose --env-file prod.env config

Check the env_file: entries declared in the Compose file:

grep -n "env_file" compose.yaml

Step-by-Step Resolution

1. Read the error’s absolute path. It tells you exactly where Compose looked, for example /home/deploy/app/.env. Check whether a file exists there:

ls -la /home/deploy/app/.env

2. If the file is simply missing, create it (or copy from a template) at that path:

cp .env.example .env

3. If the path is wrong, fix the env_file: entry. Paths are relative to the Compose file’s directory, so be explicit:

services:
  web:
    image: myapp:latest
    env_file:
      - ./config/prod.env

4. If you pass --env-file, give the correct location and run Compose from a stable directory:

docker compose --env-file ./deploy/prod.env up -d

5. To make a referenced env file optional (Compose v2.24+), mark it required: false so a missing file does not abort:

services:
  web:
    env_file:
      - path: ./config/local.env
        required: false

6. In CI, generate the env file before running Compose, since .env is usually git-ignored:

printf "DB_HOST=%s\nDB_PASS=%s\n" "$DB_HOST" "$DB_PASS" > .env
docker compose up -d

7. Re-run and confirm the stack starts:

 ✔ Container app-web-1  Started

Prevention

• Commit a .env.example template and document the cp .env.example .env bootstrap step in your README.
• Use explicit relative paths (./config/prod.env) in env_file: so behavior does not depend on the caller’s directory.
• Always run docker compose from the project root, or pass -f and --project-directory so paths resolve predictably.
• In CI/CD, render the env file from secrets before invoking Compose, and validate with docker compose config first.
• Mark genuinely optional env files required: false so local-only overrides do not break shared deploys.

Related Errors

• no such file or directory on -f compose.yaml — the Compose file itself is missing, not the env file.
• The DB_PASS variable is not set. Defaulting to a blank string — a warning that a variable was unset, not a missing file.
• services.web.env_file must be a string or list — a malformed env_file: value rather than a missing file.
• error while interpolating ... — bad ${VAR} syntax in the Compose file, separate from env-file loading.

Frequently Asked Questions

What is the difference between the .env file and env_file:? The top-level .env supplies variables for substitution inside the Compose file. env_file: injects variables into a specific container’s environment. They are loaded independently.

Why does Compose fail instead of ignoring a missing env file? By design, so you never start a container with missing configuration silently. Provide the file, fix the path, or mark it required: false.

How are env_file paths resolved? Relative to the directory containing the Compose file, not your current shell directory. Run Compose from the project root or use explicit ./ paths to avoid surprises.

Can I make an env file optional? Yes, in Compose v2.24+ use the long form with required: false so a missing file is skipped instead of erroring. Generate Compose and env-file fixes fast with the DevOps AI prompt library.

How do I handle .env in CI where it is git-ignored? Write the file from CI secrets before running Compose, then validate with docker compose config. See more Docker guides.