In this tutorial, learn how to fix PM2 app not starting issues with this step-by-step debugging guide. Covers logs, environment setup, dependencies, and advanced troubleshooting for stable Node.js deployments.
Introduction
In modern Node.js deployments, PM2 is widely used to manage and keep applications running reliably in production. However, when an application fails to start under PM2, it can disrupt deployments, delay releases, and impact system stability.
In this guide, we walk through a structured and practical process to troubleshoot PM2 startup issues, starting from basic checks and moving toward advanced diagnostics. The goal is to help us identify problems quickly, resolve them with confidence, and build a repeatable debugging workflow that works across different environments.
Prerequisites
Before we begin, let’s ensure we have the following in place:
- A Linux OS installed on dedicated server or KVM VPS.
- A basic programming knowledge.
- PM2 app
Learn how to fix PM2 app not starting issues with this step-by-step debugging guide.
1. Verify PM2 and Node Environment
Before diving into logs or configurations, we confirm that the runtime environment is correct.
pm2 -v
node -v
which node
We ensure:
- PM2 is installed globally and accessible
- Node.js version matches the application requirement
- The Node binary path is correct (especially important when using NVM)
If we are using NVM, PM2 may not pick the correct Node version after reboot. In such cases:
pm2 startup
pm2 save
This ensures PM2 uses the correct environment on system restart.
2. Check PM2 Process List and Status
We inspect whether PM2 attempted to start the app and what state it is in.
pm2 list
Common statuses:
errored→ application crashed repeatedlystopped→ manually stopped or failed to startonline→ running successfully
For deeper insight:
pm2 describe <app_name>
This gives details about restart count, script path, and environment variables.
3. Analyze Logs Carefully
Logs are the most reliable source of truth. We should not skip this step.
pm2 logs <app_name>
Or directly:
tail -f ~/.pm2/logs/<app_name>-error.log
tail -f ~/.pm2/logs/<app_name>-out.log
We look for:
- Syntax errors
- Missing modules
- Port conflicts
- Permission issues
If logs are unclear, we restart with fresh logs:
pm2 flush
pm2 restart <app_name>
4. Validate Application Start Command
Many failures come from incorrect start commands.
Example:
pm2 start app.js
or for frameworks:
pm2 start npm --name "app" -- start
We verify:
- Entry file exists (app.js, server.js, etc.)
- Script path is correct
- Working directory is correct
If needed:
pm2 start app.js --cwd /var/www/app
5. Check Dependencies and Build Issues
If the application depends on packages or build steps:
npm install
npm run build
Common issues:
- Missing node_modules
- Build artifacts not generated
- Version conflicts
If using production mode:
npm install --production
6. Environment Variables and Config
Applications often fail silently due to missing environment variables.
We verify .env or config files:
printenv
Or pass variables via PM2:
pm2 start app.js --env production
For ecosystem config:
module.exports = {
apps: [
{
name: "app",
script: "app.js",
env: {
NODE_ENV: "production",
PORT: 3000
}
}
]
}
Then:
pm2 start ecosystem.config.js
7. Port Conflicts and Network Issues
If the application cannot bind to a port, it will fail immediately.
Check port usage:
sudo lsof -i :3000
Kill conflicting process:
sudo kill -9 <PID>
Or change the port in configuration.
8. File Permissions and Ownership
Permission issues are common on production servers.
We ensure correct ownership:
sudo chown -R $USER:$USER /var/www/app
And proper permissions:
chmod -R 755 /var/www/app
If PM2 runs under a different user (like root vs ubuntu), this must be consistent.
9. Restart Strategy and Crash Loops
If the app keeps restarting, PM2 may be masking the real issue.
We check restart count:
pm2 list
Then run the app manually:
node app.js
This often reveals hidden runtime errors instantly.
10. Debug with PM2 in Verbose Mode
We can run PM2 with more visibility:
DEBUG=* pm2 start app.js
Or attach to process:
pm2 monit
This shows CPU, memory, and real-time logs.
11. System-Level Issues
Sometimes the issue is not PM2 or the app, but the server itself.
We check:
Disk space:
df -h
Memory:
free -m
Open file limits:
ulimit -n
Low resources can prevent applications from starting.
12. Reset PM2 State (Advanced Fix)
If PM2 itself is corrupted or behaving unexpectedly:
pm2 kill
pm2 resurrect
Or completely reset:
rm -rf ~/.pm2
npm install -g pm2
Then restart the application.
Conclusion
In production environments, an application failing to start under PM2 is rarely an isolated issue. It is typically a signal that something deeper in the stack requires attention, whether that is environment configuration, dependency management, or system-level constraints.
A structured debugging approach allows us to move beyond trial-and-error and instead work with clarity and intent. By validating the runtime environment, reviewing logs carefully, confirming application entry points, and checking system resources, we establish a reliable process that can be reused across deployments and teams.