Every check, and why it matters
| Check | Level | What goes wrong otherwise |
|---|---|---|
Missing = | error | the line is ignored, the variable is undefined |
Invalid key name (digit first, -, ., spaces) | error | most loaders skip it; shells can't export it |
| Unterminated quote | error | the value is lost or swallows following lines |
| Duplicate key | warning | one definition silently wins (the last one in dotenv) |
| Empty value | warning | KEY= is set but empty, often a forgotten secret |
Unquoted # | warning | Node's dotenv reads ab#cd as ab |
Spaces around = | warning | docker run --env-file rejects the name |
| Placeholder value | warning | changeme, xxx, your_key_here reach production |
| UTF-8 BOM | warning | first key name gets an invisible character in some tools |
Inline comment, $, lower-case key | note | behaviour differs between loaders |
The .env syntax that works everywhere
# comments on their own line DATABASE_URL=postgres://app:secret@db:5432/app APP_NAME="Acme Billing" # double quotes for spaces SMTP_PASSWORD='p@ss#w$rd' # single quotes: no # cut, no $ expansion PRIVATE_KEY="-----BEGIN KEY-----\nMIIE…\n-----END KEY-----" FEATURE_FLAGS=search,billing # lists as comma-separated strings
- Names:
A-Z,0-9,_, not starting with a digit. - No spaces around
=. - Quote anything with spaces,
#or$; single quotes keep it fully literal. - Multi-line values: one line with
\nescapes inside double quotes.
The guide how to fix .env errors walks through the runtime symptoms ("undefined", wrong value, works locally but not in production) and their causes.
Validating .env files in CI
To stop broken templates from being merged, lint .env.example in your pipeline. The open-source dotenv-linter covers most of the same checks:
# GitHub Actions / any CI curl -sSfL https://raw.githubusercontent.com/dotenv-linter/dotenv-linter/master/install.sh | sh -s ./bin/dotenv-linter .env.example
At runtime, validate the variables your app needs with a schema (zod, envalid, pydantic-settings) so a missing key fails at startup, not on the first request. After validating, the .env formatter and ENV cleaner tidy the file.