Maaz Zindani

Loading the index…

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

Environment variables from .env are undefined when the app runs under PM2

Errorprocess.env.DB_HOST is undefined (works with node app.js, not with pm2 start)

Short answer

dotenv reads .env from the process's current directory, and it never overwrites a variable that already exists. Under PM2 either rule can go wrong: PM2 may start the app from another directory, the shell or ecosystem file may already set the name, or the env_production block was never selected with --env.

  • Applies to Node.js 22, PM2 (current docs), dotenv (current README)
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print where the process runs and what it sees. The directory shows whether dotenv can find the file, and the value shows who set it.

    console.log(process.cwd(), process.env.DB_HOST);
  2. 2Match what you see, then jump to its fix

    1. 1process.cwd() is not your project folder, and DB_HOST is undefinedPM2 starts the app in a different directory than the one holding .envFix
    2. 2The value is not undefined, but it is not the one in .envThe variable already exists, so dotenv leaves it aloneFix
    3. 3Values defined under env_production are undefined; values under env appearThe env_production block exists, but --env was not passedFix

What does the error look like?

  • process.env.DB_HOST is undefined (works with node app.js, not with pm2 start)
  • Wrong value in process.env: the .env value is ignored

Cause 1 of 3

PM2 starts the app in a different directory than the one holding .env

1Check

dotenv's default is the .env file in process.cwd(). PM2 launches the app from its cwd setting, so a config file stored elsewhere, or a start command run from another folder, moves it.

// top of app.js
console.log('cwd:', process.cwd());
// then
pm2 logs my-app --lines 5 --nostream

2Fix

Set cwd in the ecosystem file, or give dotenv an absolute path so the working directory stops mattering. On Node.js 20.6 and later you can also let Node.js load the file with node_args.

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'my-app',
    script: './app.js',
    cwd: '/srv/my-app',
    node_args: '--env-file=.env',
  }],
};

// or in app.js
require('dotenv').config({ path: require('path').resolve(__dirname, '.env') });

3Verify

Restart from the file and read the log line again.

pm2 start ecosystem.config.js
pm2 logs my-app --lines 5 --nostream

Confirmed by pm2.keymetrics.io

Did this fix it?

Cause 2 of 3

The variable already exists, so dotenv leaves it alone

1Check

By default dotenv never modifies a variable that is already set. PM2 passes your shell's environment to the app, and the env block of the ecosystem file is applied after that and wins over the shell. Either source can hold an old value.

printenv DB_HOST
grep -n "DB_HOST" ecosystem.config.js

2Fix

Remove the stale value from the shell or the env block, or tell dotenv to override.

require('dotenv').config({ override: true });

3Verify

The log shows the value from .env.

pm2 restart my-app && pm2 logs my-app --lines 5 --nostream

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The env_production block exists, but --env was not passed

1Check

PM2 applies env_<name> blocks only when you name them. A plain pm2 start uses env only.

grep -n "env_" ecosystem.config.js

2Fix

Start or restart with the environment name.

pm2 start ecosystem.config.js --env production

3Verify

The production values show in the app's log output.

pm2 logs my-app --lines 5 --nostream

Confirmed by pm2.keymetrics.io

Did this fix it?

How do I stop it coming back?

  • Set cwd in the ecosystem file for every app.
  • Keep one source for each variable: either .env or the ecosystem env block, not both.
  • Use the same start command in deploy scripts every time, including --env.

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.