process.env.MY_VARIABLE is undefined even though it is in the .env file
console.log(process.env.PORT) prints undefinedShort answer
process.env only holds variables that exist in the process environment. Node.js does not load a .env file unless you ask it to, with the --env-file flag or a library such as dotenv. Load the file before any code reads the variable, and start the app from the folder that holds it.
Fix it fast
1Find out which cause you have
Print every variable name the process can see. If your key is not in the list, the file was never loaded.
node -e "console.log(Object.keys(process.env).filter(k => k.includes('PORT')))"2Match what you see, then jump to its fix
- 1
The key is missing from the list above, and no flag or library loads the fileNothing loads the .env fileFix - 2
dotenv is installed, yet a module-level constant is still undefineddotenv runs after the code that reads the variableFix - 3
Works with npm start in the project root, fails from a process manager, systemd or a script in another folderThe app starts from a different folder than the one with .envFix - 4
The value is not undefined but it is not the one in the fileThe variable already exists in the shell with another valueFix
- 1
What does the error look like?
console.log(process.env.PORT) prints undefined
Cause 1 of 4
Nothing loads the .env file
1Check
Look at how the app starts. A plain node index.js reads no file.
grep -n "dotenv\|env-file" package.json
grep -rn "dotenv" --include=*.js --include=*.mjs --include=*.ts . --exclude-dir=node_modules | head2Fix
Start Node.js with --env-file (added in v20.6.0), or use dotenv. If the file may be absent in production, use --env-file-if-exists (v22.9.0 and later).
node --env-file=.env index.js3Verify
The value now prints.
node --env-file=.env -e "console.log(process.env.PORT)"Confirmed by nodejs.org
Cause 2 of 4
dotenv runs after the code that reads the variable
1Check
Imports run first. If another module reads process.env while it is being imported, dotenv has not run yet. In ES modules, imports are evaluated in order, so the dotenv import must come first.
grep -n "import\|require" index.js | head2Fix
Load dotenv as the very first line of the entry file.
// index.mjs
import 'dotenv/config';
import './server.mjs';3Verify
The first read after startup returns the value.
node index.mjsConfirmed by github.com
Cause 3 of 4
The app starts from a different folder than the one with .env
1Check
Both --env-file and dotenv look for the path relative to the current working directory. A missing file given to --env-file raises an error, but a dotenv default load simply finds nothing.
pwd
ls -la .env2Fix
Run from the project folder, or pass an absolute path.
node --env-file=/srv/my-app/.env /srv/my-app/index.js3Verify
Run it from any folder.
cd / && node --env-file=/srv/my-app/.env -e "console.log(process.env.PORT)"Confirmed by nodejs.org
Cause 4 of 4
The variable already exists in the shell with another value
1Check
When a variable is set in both the environment and the file, the environment value wins. dotenv also skips keys that already exist unless override is true.
printenv PORT2Fix
Unset the shell variable, or in dotenv enable override.
unset PORT
# or, in code:
require('dotenv').config({ override: true });3Verify
The value now comes from the file.
node --env-file=.env -e "console.log(process.env.PORT)"Confirmed by github.com
How do I stop it coming back?
- Load the env file in one place: the start script or the first import of the entry file.
- Give production values through the process manager or host, and keep .env for local work.
- Fail fast at startup when a required variable is missing instead of letting undefined travel.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
ng serve says it cannot determine the project or target
Cannot determine project for command.
The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.
3 causes, each with a fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
ng serve cannot find the dev-server builder package
Could not find the implementation for builder @angular/build:dev-server
The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.
3 causes, each with a fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix