PM2 keeps the old environment variables after restart --update-env
Use --update-env to update environment variablesShort 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.
Fix it fast
1Find out which cause you have
Print what PM2 stored for the process, then compare it with what you expected.
pm2 env 02Match what you see, then jump to its fix
- 1
PM2 prints: Use --update-env to update environment variablesrestart was run without --update-envFix - 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
You 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
A variable you deleted from the shell is still present in the processAn inherited variable that must be removed, not changedFix
- 1
What does the error look like?
Use --update-env to update environment variablesthe 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_URL2Fix
Add --update-env, in the same shell where the variable is set.
API_URL=https://new.example.com pm2 restart my-app --update-env3Verify
PM2 now lists the new value.
pm2 env 0 | grep API_URLConfirmed by pm2.keymetrics.io
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-env3Verify
The renamed variable appears in the process environment.
pm2 env 0 | grep MYAPP_NAMEConfirmed by pm2.keymetrics.io
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.js2Fix
Restart by passing the config file and the environment name.
pm2 restart ecosystem.config.js --env production3Verify
The value from env_production is shown.
pm2 env 0Confirmed by pm2.keymetrics.io
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 02Fix
Delete the process and start it again from the config file.
pm2 delete my-app
pm2 start ecosystem.config.js
pm2 save3Verify
The removed variable no longer appears.
pm2 env 0Confirmed by pm2.keymetrics.io
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:
- 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
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
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
process.env.NODE_ENV is undefined in a Node.js app
console.log(process.env.NODE_ENV) prints undefined
Node.js does not set NODE_ENV for you.
5 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
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