Symptom 1: the variable is undefined
1. The file isn't the one being loaded
- The name must be exactly
.env(or.env.localin Next.js/Vite), notenv,.env.txtor.ENV. Windows Explorer likes to add.txt. - dotenv looks in the current working directory, not next to the script. Run
node -e "console.log(process.cwd())"from where you start the app. - In monorepos, each app usually needs its own
.env, or an explicit path:dotenv.config({ path: "../../.env" }).
2. dotenv runs after the code that reads the variable
// ❌ db.js reads process.env.DATABASE_URL at import time, before dotenv ran
import { db } from "./db.js";
import "dotenv/config";
// ✅ load first (or start with: node --env-file=.env app.js)
import "dotenv/config";
import { db } from "./db.js";3. A typo or invalid key name
DATABSE_URL vs DATABASE_URL, or names like 2FA_SECRET and API-KEY that most loaders skip silently. Keys must match [A-Za-z_][A-Za-z0-9_]*. Compare what the code reads with what the file defines using the missing env detector, which can scan your source code.
4. Client code can't see server variables
Browsers only get variables with a public prefix: NEXT_PUBLIC_ in Next.js, VITE_ in Vite. Everything else is undefined in client components by design. See NEXT_PUBLIC_ variables explained.
5. The process started before you edited the file
Node reads the file once at startup. next dev reloads .env* files when they change; Vite, plain Node, and most other servers need a restart. NEXT_PUBLIC_/VITE_ values are baked in at build time, so production needs a rebuild.
Symptom 2: the value is wrong or cut off
6. The key is defined twice
dotenv, python-dotenv and Docker Compose all use the last definition in a file. Someone adds a test value at the bottom and forgets it. The ENV cleaner removes the earlier duplicates and keeps the effective value.
7. An unquoted # cuts the value
DB_PASSWORD=ab#cd # Node dotenv reads "ab", python-dotenv reads "ab#cd" DB_PASSWORD="ab#cd" # every loader reads "ab#cd"
8. $ is expanded
dotenv-expand, Docker Compose and shells replace $NAME with another variable, often an empty one. pa$word becomes pa. Use single quotes ('pa$word') to keep it literal; in compose.yaml write $$.
9. Smart quotes or invisible characters
Copying from a document turns " into “ ”, which loaders treat as part of the value. A UTF-8 BOM at the start of the file can glue itself to the first key name. Retype the quotes in a code editor and save as UTF-8 without BOM; the validator flags a BOM.
Symptom 3: works locally, fails in production
10. The host never sees your .env
Vercel, Netlify, Railway, Render, Fly.io and Kubernetes inject variables from their own settings; your .env is (correctly) not deployed. Copy every key into the host, per environment. Guides: Vercel environment variables, GitHub Actions secrets.
11. Environments drifted apart
A key was added locally but never in staging or production. Export the host's values and compare them with the ENV diff checker; removed keys are the usual culprit.
12. The file is sourced by a shell or Docker
| Line | dotenv / python-dotenv | source .env in bash | docker run --env-file |
|---|---|---|---|
APP_NAME=My App | My App | error: App: command not found | My App |
KEY = value | value | error | rejected (space in name) |
KEY="value" | value | value | "value" with quotes |
| CRLF line endings | handled | value ends in \r | value ends in \r |
If one file has to work everywhere: no spaces around =, quote values with spaces, LF line endings. The .env formatter normalises a file without changing values.
A 60-second debugging routine
- Print what the process actually sees:
node -e 'require("dotenv").config(); console.log(Object.keys(process.env).filter(k => k.startsWith("DB")))'. - Paste the file into the .env validator and fix every error and warning.
- Check required keys against the code with the missing env detector.
- Restart the dev server; rebuild if the variable is public (
NEXT_PUBLIC_,VITE_). - For production, compare host settings with your local file in the ENV diff checker.
If a real secret ended up in git while you were debugging, that's a security incident, not an error: rotate it, then follow how to hide .env from git.
Frequently asked questions
Why is my env variable undefined?
The file isn't loaded (wrong name, wrong working directory, dotenv called too late), the key has a typo, or you're reading a server-only variable in browser code. Print process.cwd() and the loaded keys to see which one it is.
Why does my .env work locally but not in production?
Production hosts don't read .env files. Add every variable in the host's environment settings, and rebuild if public (NEXT_PUBLIC_/VITE_) values changed.
Why is part of my value missing?
Usually an unquoted # (Node's dotenv treats it as a comment start) or a $ that was expanded as a variable. Wrap the value in quotes; single quotes also stop expansion.
Which value wins if a key appears twice?
The last one, in dotenv, python-dotenv and Docker Compose. A variable that is already set in the real environment beats the file in all of them unless you enable override.
Do I need to restart after editing .env?
Usually yes. next dev reloads env files automatically, but Node, Vite and most frameworks read the file only at startup, and public variables need a rebuild.