docker-compose-env-file-mandatory-fresh-clone
I diagnosed and reproduced the issue, then wrote a verified, self-contained solution to ~/solution.md.
Root cause: The short/string form of env_file is implicitly required: true. Compose stats the file at config-resolution time, so on a fresh clone where .env is gitignored (but .env.example is tracked), docker compose up/config aborts with env file .../.env not found and exit 1.
Fix (Compose spec ≥ 2.24):
services:
app:
env_file:
- path: .env
required: false # missing file is skipped
Plus document cp .env.example .env in the README, and keep .env.example tracked (!.env.example in .gitignore).
Verification (actually run, Compose 2.40.3 / Docker 29.1.3):
| Case | Result |
|---|---|
| Fresh clone, old short form (negative control) | exit 1 — file not found |
Fresh clone, long form required: false |
exit 0 |
Long form with .env present |
exit 0, FOO: bar injected |
The negative control is the old short-form exiting 1; the fixed long-form exits 0 in a scratch dir without .env — matching the GAP-068 requirement. The solution also notes the silent-skip caveat (validate required vars at app boot) and the distinction from root-level .env interpolation.
# Evidence - Problem class: docker-compose-env-file-mandatory-fresh-clone - Model: openrouter/deepseek/deepseek-v4.1-flash - Solved: 2026-09-11T16:42:45.040Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "docker compose up fails on fresh clone: env_file [.env] mandatory but .env gitignored. Fix: long-form env_file [{path: .env, required: false}] (compose spec v2.24+) + document cp .env.example .env before compose up. Verify: scratch dir without .env -> docker compose config exit 0; negative control with old short-form -> exit 1. Proven hermes-canopy GAP-068 commit ce3e1dc.", "environment": "docker-compose-2.40", "language": "yaml", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "docker-compose-env-file-mandatory-fresh-clone", "provider": "openrouter", "solved_at": "2026-09-11T16:42:45.040Z", "version": ""}I diagnosed and reproduced the issue, then wrote a verified, self-contained solution to ~/solution.md.
Root cause: The short/string form of env_file is implicitly required: true. Compose stats the file at config-resolution time, so on a fresh clone where .env is gitignored (but .env.example is tracked), docker compose up/config aborts with env file .../.env not found and exit 1.
Fix (Compose spec ≥ 2.24):
services:
app:
env_file:
- path: .env
required: false # missing file is skipped
Plus document cp .env.example .env in the README, and keep .env.example tracked (!.env.example in .gitignore).
Verification (actually run, Compose 2.40.3 / Docker 29.1.3):
| Case | Result |
|---|---|
| Fresh clone, old short form (negative control) | exit 1 — file not found |
Fresh clone, long form required: false |
exit 0 |
Long form with .env present |
exit 0, FOO: bar injected |
The negative control is the old short-form exiting 1; the fixed long-form exits 0 in a scratch dir without .env — matching the GAP-068 requirement. The solution also notes the silent-skip caveat (validate required vars at app boot) and the distinction from root-level .env interpolation.
# Evidence - Problem class: docker-compose-env-file-mandatory-fresh-clone - Model: openrouter/deepseek/deepseek-v4.1-flash - Solved: 2026-09-11T16:42:45.040Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "docker compose up fails on fresh clone: env_file [.env] mandatory but .env gitignored. Fix: long-form env_file [{path: .env, required: false}] (compose spec v2.24+) + document cp .env.example .env before compose up. Verify: scratch dir without .env -> docker compose config exit 0; negative control with old short-form -> exit 1. Proven hermes-canopy GAP-068 commit ce3e1dc.", "environment": "docker-compose-2.40", "language": "yaml", "model": "openrouter/deepseek/deepseek-v4.1-flash", "problem_class": "docker-compose-env-file-mandatory-fresh-clone", "provider": "openrouter", "solved_at": "2026-09-11T16:42:45.040Z", "version": ""}