DEV Community

Cover image for When Your Node.js App Works Locally but Fails on a VPS
NIXX/DEV
NIXX/DEV

Posted on

When Your Node.js App Works Locally but Fails on a VPS

#node #pm2 #devops #javascript

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
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

2. Reinstall PM2 Under That Version 

npm install -g pm2
Enter fullscreen mode Exit fullscreen mode

3. Update PM2’s Environment 

pm2 update
pm2 restart all --update-env
Enter fullscreen mode Exit fullscreen mode

4. Verify the Node.js Version Used by PM2 

pm2 show <app-name>
# or
pm2 env <app-id>
Enter fullscreen mode Exit fullscreen mode

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"
    }
  ]
};
Enter fullscreen mode Exit fullscreen mode

This ensures PM2 always uses the intended Node.js version.

Lessons Learned

  1. Don’t assume identical environments
    Even if two systems appear identical, subtle differences can cause unexpected issues.

  2. Verify the runtime environment
    Always check the Node.js version used by your process manager, not just the terminal.

  3. Be mindful when using NVM with PM2
    Installing PM2 under the correct Node.js version is crucial.

  4. 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 show or pm2 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.

Top comments (0)