This content originally appeared on DEV Community and was authored by NIXX/DEV
You build a Node.js application.
It runs perfectly on your development machine.
You deploy it to a VPS… and suddenly, it stops working.
Same code. Same environment. Or so you think.
If you’re a developer, chances are you’ve encountered this frustrating scenario. I recently faced this exact issue, and after three days of debugging, I discovered the unexpected culprit: PM2 was using a different Node.js version than the one installed on the server.
This article shares my experience and how you can avoid the same pitfall.
The Problem
After deploying my Node.js application to a VPS, the app failed to run correctly. What made the situation confusing was that:
- The operating system on both my development machine and the VPS was identical.
- The Node.js version appeared to be the same when I checked using:
node -v
Despite this, the application continued to behave unexpectedly. I spent hours reviewing logs, checking dependencies, and verifying configurations—yet nothing seemed out of place.
The Discovery
After three days of troubleshooting, the solution finally revealed itself.
I was using PM2 as a process manager to run the application. While the terminal showed the correct Node.js version, PM2 was actually running the app using an older Node.js binary.
This mismatch caused the application to fail, even though everything appeared correct at first glance.
To confirm this, you can inspect the environment PM2 is using:
pm2 show <app-name>
# or
pm2 env <app-id>
These commands reveal the Node.js version and environment variables associated with the running process.
Why This Happens
This issue commonly occurs when:
- Node Version Manager (NVM) is used to manage multiple Node.js versions.
- PM2 is installed globally under a different Node.js version.
- The shell environment differs from the one PM2 uses to start applications.
As a result, running node -v in the terminal may not reflect the Node.js version that PM2 is actually using.
The Solution
Here are the steps to ensure PM2 uses the correct Node.js version:
1. Use the Desired Node.js Version
nvm use <node_version>
2. Reinstall PM2 Under That Version
npm install -g pm2
3. Update PM2’s Environment
pm2 update
pm2 restart all --update-env
4. Verify the Node.js Version Used by PM2
pm2 show <app-name>
# or
pm2 env <app-id>
Alternative Approach
You can explicitly define the Node.js interpreter in your PM2 ecosystem file:
module.exports = {
apps: [
{
name: "my-app",
script: "app.js",
interpreter: "/home/username/.nvm/versions/node/v18.17.0/bin/node"
}
]
};
This ensures PM2 always uses the intended Node.js version.
Lessons Learned
Don’t assume identical environments
Even if two systems appear identical, subtle differences can cause unexpected issues.Verify the runtime environment
Always check the Node.js version used by your process manager, not just the terminal.Be mindful when using NVM with PM2
Installing PM2 under the correct Node.js version is crucial.Use ecosystem configuration for consistency
Explicitly defining the interpreter can prevent future surprises.
Quick Checklist
- Confirm Node.js version with
node -v - Check PM2 environment using
pm2 showorpm2 env - Use
nvm use <version>before installing PM2 - Restart PM2 with
--update-env - Optionally specify the interpreter in the ecosystem file
Debugging deployment issues can be frustrating, especially when everything appears to be configured correctly. In my case, the problem wasn’t the code or the server—it was a Node.js version mismatch within PM2.
If your Node.js application works locally but fails on a VPS, make sure to verify the runtime environment used by your process manager. This simple check could save you days of unnecessary debugging.
I hope this helps someone out there avoid the same headache.
This content originally appeared on DEV Community and was authored by NIXX/DEV
NIXX/DEV | Sciencx (2026-04-11T07:35:00+00:00) When Your Node.js App Works Locally but Fails on a VPS. Retrieved from https://www.scien.cx/2026/04/11/when-your-node-js-app-works-locally-but-fails-on-a-vps/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.