Maaz Zindani

Loading the index…

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

PM2 keeps the old environment variables after restart --update-env

ErrorUse --update-env to update environment variables

Short answer

A plain pm2 restart reuses the environment stored at first start. --update-env only re-reads the environment of the shell that runs the command, and it ignores variables named like PM2 options. If the value still looks old, pass the variable in that same command, or delete the process and start it again.

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

Fix it fast

  1. 1Find out which cause you have

    Print what PM2 stored for the process, then compare it with what you expected.

    pm2 env 0
  2. 2Match what you see, then jump to its fix

    1. 1PM2 prints: Use --update-env to update environment variablesrestart was run without --update-envFix
    2. 2--update-env is used and the shell value is correct, but the variable is still not appliedThe variable is named like a PM2 optionFix
    3. 3You edited env_production in ecosystem.config.js, but the app has the old or the default env blockThe value lives in the ecosystem file, in an env_<name> blockFix
    4. 4A variable you deleted from the shell is still present in the processAn inherited variable that must be removed, not changedFix

What does the error look like?

  • Use --update-env to update environment variables
  • the app still prints the old value after pm2 restart

Cause 1 of 4

restart was run without --update-env

1Check

pm2 restart and pm2 reload keep the environment the process was started with, and print a hint to say so. The variable you exported in your shell afterwards is not read.

export API_URL=https://new.example.com
pm2 restart my-app
pm2 env 0 | grep API_URL

2Fix

Add --update-env, in the same shell where the variable is set.

API_URL=https://new.example.com pm2 restart my-app --update-env

3Verify

PM2 now lists the new value.

pm2 env 0 | grep API_URL

Confirmed by pm2.keymetrics.io

Did this fix it?

Cause 2 of 4

The variable is named like a PM2 option

1Check

PM2 ignores shell variables whose names match one of its own options (for example name, instances or watch) and variables starting with pm_ or axm_. Compare your variable name with that list.

env | grep -i -E '^(name|instances|watch|pm_|axm_)'

2Fix

Rename the variable to something specific to your app, such as MYAPP_NAME, and read the new name in the code.

MYAPP_NAME=billing pm2 restart my-app --update-env

3Verify

The renamed variable appears in the process environment.

pm2 env 0 | grep MYAPP_NAME

Confirmed by pm2.keymetrics.io

Did this fix it?

Cause 3 of 4

The value lives in the ecosystem file, in an env_<name> block

1Check

The block is only used when you name it with --env, and it must match the part after env_. Restarting by app name does not read the edited file at all.

grep -n -A4 "env_" ecosystem.config.js

2Fix

Restart by passing the config file and the environment name.

pm2 restart ecosystem.config.js --env production

3Verify

The value from env_production is shown.

pm2 env 0

Confirmed by pm2.keymetrics.io

Did this fix it?

Cause 4 of 4

An inherited variable that must be removed, not changed

1Check

Restart and --update-env add or overwrite variables. PM2's own notes say a process that already received the full shell environment keeps it, and has to be deleted and started again.

pm2 env 0

2Fix

Delete the process and start it again from the config file.

pm2 delete my-app
pm2 start ecosystem.config.js
pm2 save

3Verify

The removed variable no longer appears.

pm2 env 0

Confirmed by pm2.keymetrics.io

Did this fix it?

How do I stop it coming back?

  • Keep environment values in the ecosystem file (env and env_production) and always restart with the file and --env.
  • Do not use variable names that match PM2 option names.
  • After you change the setup, run pm2 save so a reboot starts the same configuration.

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.