Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

process.env.NODE_ENV is undefined in a Node.js app

Errorconsole.log(process.env.NODE_ENV) prints undefined

Short 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.

  • Applies to Node.js 22, Node.js 24, PM2 6, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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)"
  2. 2Match what you see, then jump to its fix

    1. 1The variable is undefined in a plain `node app.js` run, and everything else works.Nothing sets NODE_ENVFix
    2. 2NODE_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. 3The file has NODE_ENV=production, but process.env.NODE_ENV is still undefined.The value lives in a .env file that nobody loadsFix
    4. 4It 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. 5The variable is not undefined but the string "undefined", so `if (process.env.X)` is true.undefined was assigned and became the text 'undefined'Fix

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=production

3Verify

Print it from the process.

NODE_ENV=production node -e "console.log(process.env.NODE_ENV)"

Confirmed by nodejs.org

Did this fix it?

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.json

2Fix

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 build

Confirmed by github.com

Did this fix it?

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 .env

2Fix

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

Did this fix it?

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.js

2Fix

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 production

3Verify

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 --nostream

Confirmed by pm2.keymetrics.io

Did this fix it?

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

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.