Fixing 'PM2 Node Not Found' and Production Process Errors

For DevOps engineers managing Node.js on Ubuntu, few challenges are as frustrating as encountering a successful CI/CD build that results in a dead application due to PM2 being unable to locate the Node binary. This "Node not found" error is a classic symptom of path misalignment, often arising in environments where Node is managed via NVM (Node Version Manager).

The Root Cause: Non-Interactive Shells vs. NVM

NVM is specifically designed for interactive shells. When you log in via SSH, your .bashrc or .zshrc loads the NVM environment correctly. However, system services (like systemd) and CI/CD runners (such as GitHub Actions) typically operate in non-interactive shells. Consequently, if PM2 is started as a background service, it may lose the reference to the specific version of Node it was configured to use, reverting either to a system default or failing entirely.

Step 1: Conducting a 'Which' Command Audit

To begin resolving the issue, you first need to identify the location of your active Node binary. Execute the command:

which node

If the output path resembles /home/ubuntu/.nvm/versions/node/v18.x/bin/node, you have a version-specific path that should be hardcoded into your PM2 startup script for consistency.

Step 2: Generating a Robust Startup Script

To ensure your application runs smoothly after a reboot, avoid manually restarting PM2. Instead, use the built-in startup system by executing:

pm2 startup systemd

This command generates a line that you must run with sudo, creating a systemd unit file. The key to achieving stability is to edit this unit file (usually located in /etc/systemd/system/) and ensure the Environment=PATH=... line explicitly includes your NVM bin directory.

Step 3: Utilizing Ecosystem Files for Path Consistency

For consistent application management, rather than running pm2 start app.js, always use an ecosystem.config.js file. This practice allows you to define an interpreter attribute. By setting:

interpreter: '/home/ubuntu/.nvm/versions/node/v20.x/bin/node'

you bypass the shell's PATH entirely, ensuring PM2 utilizes the exact version of Node required by your application logic.

Conclusion

Effective process management is crucial for maintaining production stability. By hardcoding paths and leveraging systemd, you minimize the "human element" in deployments, guaranteeing that your applications remain online through reboots and high-pressure updates. Implement these steps to ensure seamless operations in your Node.js environment.