The 12 most common .env errors (and their fixes)
If you're reading this, something in your .env isn't loading. Start with the validator — it catches ~80% of the issues on this list. For the rest, walk through these in order.
1. process.env.KEY is undefined
Check, in order:
- The file is named exactly
.env(or.env.local). Notenv, not.env.txt. - The file is in the project root (or wherever your framework expects it).
require("dotenv").config()runs before the read, not after.- The key exists in the file and has no typo.
2. Duplicate keys — wrong value wins
dotenv keeps the first occurrence. Most other parsers keep the last. If your local looks right but prod sees the other value, you've got a dupe. The cleaner removes duplicates in one click.
3. Missing quotes around spaces
# ❌ breaks
APP_NAME=My Awesome App
# ✅ fine
APP_NAME="My Awesome App"4. Unterminated quotes swallowing the rest of the file
# ❌ every key after this is broken
SECRET="abc
DATABASE_URL=postgres://...
JWT_SECRET=...The validator flags these with the exact line number.
5. Invalid key names
Keys must match [A-Za-z_][A-Za-z0-9_]*. Starting with a digit, containing a dash, or using a space is invalid and silently ignored by most parsers.
6. Values wrapped in smart quotes
Copy-pasting from a doc often turns " into " — visually identical, functionally broken. Retype quotes inside a real text editor.
7. Windows line endings
\r\n vs \n. Most modern parsers handle both, but legacy dotenv versions on Linux servers will choke. Configure your editor to use LF for .env files, or run it through the formatter.
8. NEXT_PUBLIC_ missing for client code
In Next.js, only variables prefixed with NEXT_PUBLIC_ are available in the browser. If you see undefined only on the client, rename the variable.
9. Variables not reloading after change
Node-based frameworks cache process.env at boot. After editing .env, restart the dev server. Next.js hot-reloads .env.local only on page refresh.
10. Staging/prod drift
Local works, deploy fails. Run the diff checker between the two files — you'll see exactly which keys are missing on one side.
11. Values with $ getting interpolated
Some dotenv parsers expand $VAR references. Either escape \$, use single quotes (most parsers don't interpolate inside single quotes), or disable expansion in the parser config.
12. Leaked secret in git history
A leaked secret isn't really an "error" — it's a security incident. Rotate immediately, then follow the best-practices checklist. Future pushes: scan before sending with the leak checker.
FAQ
Why is my env variable undefined?
Almost always one of: the file wasn't loaded before the read, the key has a typo, or the file is in the wrong directory. Check the load call runs first, verify the key exactly, and print process.env keys to confirm the file loaded at all.
Why does my .env work locally but break in production?
Production hosts (Vercel, Railway, Fly) usually don't read .env files — they inject variables via a dashboard. Make sure every key from your local .env exists in the host's env config, including NEXT_PUBLIC_ prefixes.
Why is the value including the #?
Inline comments require a space before the hash: VALUE=foo # ok vs VALUE=foo#bad. Without the space, some parsers include the hash in the value.
Still stuck?
Paste the file into the validator — if it doesn't surface anything, the problem is outside the file: load order, framework config, or host environment. For host-specific issues, the how to use dotenv guide has framework-specific checklists.