guide9 min readBy Aliniyaz Mamat · updated

How to fix .env file errors (complete troubleshooting)

To fix .env file errors, start with the symptom: a variable that is undefined, a value that is wrong, or a setup that works locally but breaks in production. This guide maps each symptom to its 12 most common causes, with the exact fix and a way to check it.

Key takeaways

  • ✓undefined is almost always a load problem: wrong file name or folder, dotenv loaded too late, or a typo in the key.
  • ✓Wrong values usually come from duplicates (the last definition wins in dotenv), an unquoted #, or $ being expanded.
  • ✓"Works locally, fails in production": hosts don't read your .env file. Set every key in the host's environment settings.
  • ✓Paste the file into the .env validator first: it catches syntax errors, duplicates, unquoted # and spaces around = with line numbers.

Symptom 1: the variable is undefined

1. The file isn't the one being loaded

  • The name must be exactly .env (or .env.local in Next.js/Vite), not env, .env.txt or .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

Linedotenv / python-dotenvsource .env in bashdocker run --env-file
APP_NAME=My AppMy Apperror: App: command not foundMy App
KEY = valuevalueerrorrejected (space in name)
KEY="value"valuevalue"value" with quotes
CRLF line endingshandledvalue ends in \rvalue 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

  1. Print what the process actually sees: node -e 'require("dotenv").config(); console.log(Object.keys(process.env).filter(k => k.startsWith("DB")))'.
  2. Paste the file into the .env validator and fix every error and warning.
  3. Check required keys against the code with the missing env detector.
  4. Restart the dev server; rebuild if the variable is public (NEXT_PUBLIC_, VITE_).
  5. 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.

Related tools

Continue reading