process.env.NODE_ENV is undefined in a Node.js app
console.log(process.env.NODE_ENV) prints undefinedShort answer
Node.js does not set NODE_ENV for you. It is a convention, so the value is undefined until you pass it in. Set it where the process starts: the shell, a cross-env script on Windows, node --env-file, a systemd unit, or the PM2 ecosystem file. Then print it once at start-up to confirm.
Fix it fast
1Find out which cause you have
Print the value from inside the running process, in the same place the app starts. Do not trust the value in your terminal, because the app may be started by something else.
node -e "console.log(process.env.NODE_ENV)"2Match what you see, then jump to its fix
- 1
The variable is undefined in a plain `node app.js` run, and everything else works.Nothing sets NODE_ENVFix - 2
NODE_ENV works on Linux and macOS but fails or stays unset on a Windows developer machine.An npm script uses Unix syntax on WindowsFix - 3
The file has NODE_ENV=production, but process.env.NODE_ENV is still undefined.The value lives in a .env file that nobody loadsFix - 4
It works when you run it by hand, but undefined after a reboot or under the process manager.systemd or PM2 starts the app without your shell variablesFix - 5
The variable is not undefined but the string "undefined", so `if (process.env.X)` is true.undefined was assigned and became the text 'undefined'Fix
- 1
What does the error look like?
console.log(process.env.NODE_ENV) prints undefined
Cause 1 of 5
Nothing sets NODE_ENV
1Check
Node.js docs describe NODE_ENV as a convention, not a core feature. Your project must set it.
echo "NODE_ENV=$NODE_ENV"2Fix
Put the variable in front of the command, or export it in the shell that starts the app.
NODE_ENV=production node app.js
# or for the whole shell session
export NODE_ENV=production3Verify
Print it from the process.
NODE_ENV=production node -e "console.log(process.env.NODE_ENV)"Confirmed by nodejs.org
Cause 2 of 5
An npm script uses Unix syntax on Windows
1Check
The script line starts with NODE_ENV=production. Most Windows command prompts do not accept that form.
grep -n NODE_ENV package.json2Fix
Install cross-env and put it in front of the command. The same script then works on Windows and Unix.
npm install --save-dev cross-env
// package.json
"scripts": {
"build": "cross-env NODE_ENV=production node ./build.js"
}3Verify
Run the script on Windows and on Linux.
npm run buildConfirmed by github.com
Cause 3 of 5
The value lives in a .env file that nobody loads
1Check
Node.js does not read .env by itself. A file is loaded only when you ask for it.
cat .env2Fix
Start the app with --env-file, or call process.loadEnvFile() before you read the variable. A variable already set in the environment wins over the file. A missing file is an error unless you use --env-file-if-exists.
node --env-file=.env app.js
// or inside the code, first line
process.loadEnvFile();3Verify
Print the value again.
node --env-file=.env -e "console.log(process.env.NODE_ENV)"Confirmed by nodejs.org
Cause 4 of 5
systemd or PM2 starts the app without your shell variables
1Check
A service does not inherit your interactive shell. Look at what the unit file or the ecosystem file really passes.
grep -n Environment /etc/systemd/system/my-app.service
grep -n NODE_ENV ecosystem.config.js2Fix
In a systemd unit use the Environment directive. In PM2 put the value in env_production and start with --env production.
# /etc/systemd/system/my-app.service
Environment=NODE_ENV=production
// ecosystem.config.js
module.exports = { apps: [{
name: "api", script: "./server.js",
env_production: { NODE_ENV: "production" }
}] }
pm2 start ecosystem.config.js --env production3Verify
Restart, then read the first log line of the app. It should print the value you set (add console.log(process.env.NODE_ENV) at start-up).
sudo systemctl daemon-reload && sudo systemctl restart my-app
pm2 logs api --lines 5 --nostreamConfirmed by pm2.keymetrics.io
Cause 5 of 5
undefined was assigned and became the text 'undefined'
1Check
Assigning to process.env turns the value into a string. Assigning undefined stores the string 'undefined' rather than removing the variable.
grep -rn "process.env\.[A-Z_]* *=" src/2Fix
Use delete to remove a variable, and only assign real strings.
delete process.env.NODE_ENV;3Verify
The property is really undefined again.
node -e "process.env.X = undefined; console.log(process.env.X); delete process.env.X; console.log(process.env.X)"Confirmed by nodejs.org
How do I stop it coming back?
- Log NODE_ENV once at start-up, so a wrong value is visible in the first line of the log.
- Fail fast: if a required variable is missing, throw at start-up instead of running with undefined.
- Set the variable in one place per environment (unit file, ecosystem file or CI config), not in several.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
Related fixes
Back end
Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
EADDRINUSE means another socket already listens on that port, so Node's listen() was refused.
4 causes, each with a fixBack end
PM2 does not restart my Node.js app after it crashes
status stopped in pm2 list
PM2 restarts a crashed process on its own, so a process that stays down has a reason.
3 causes, each with a fixBack end
PM2 says the ecosystem file is malformated and refuses to start
Error [ERR_REQUIRE_ASYNC_MODULE]
PM2 prints 'malformated' whenever loading the config file throws.
3 causes, each with a fixBack end
Loading a .env file into a PM2 ecosystem config fails or gives undefined values
[PM2][ERROR] File ecosystem.config.js malformated
PM2 only passes the env block of the config to your app.
4 causes, each with a fixBack end
PM2 keeps the old environment variables after restart --update-env
the app still prints the old value after pm2 restart
A plain pm2 restart reuses the environment stored at first start.
4 causes, each with a fixBack end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fix