Node.js App Not Starting on Server— PM2 & Production Fixed [2026]
Also covers: PM2 app not starting · Node.js app crashing on production
⚡ First Step — Read the Logs
# Direct Node — shows error immediately
node server.js
# PM2 — view logs
pm2 logs my-app
pm2 logs my-app --lines 200
# PM2 — full process info
pm2 describe my-appThe error message tells you exactly what is wrong. Match it to the fixes below.
Diagnose — Read the Logs First
Every startup failure has a specific error message. The fix depends entirely on reading it. Here is the fastest way to see what is happening:
| Error in logs | Fix |
|---|---|
| Cannot find module | Run npm install — Fix 1 |
| undefined (env variable) | Set environment variables — Fix 2 |
| SyntaxError / ReferenceError | Code error — fix the bug then redeploy |
| EADDRINUSE: port already in use | Kill the port — Fix 4 |
| EACCES: permission denied | Port below 1024 — Fix 4 |
| MongoServerSelectionError | DB env var not set or IP not whitelisted |
| Exit code 1, no error shown | Run node server.js directly to see error |
Run npm install on the Server
Cannot find module — missing node_modulesnode_modules is in .gitignore and never deployed. After every deployment or git pull, you must run npm install on the server.
cd /home/ubuntu/myapp
# Install all dependencies
npm install
# For production — faster, deterministic, no devDependencies
npm ci --omit=dev
# Verify a specific package installed
ls node_modules | grep express
# Then restart
pm2 restart my-app
# or
node server.jsAdd npm install (or npm ci) to your deployment script or CI/CD pipeline so it runs automatically on every deploy.
Set Environment Variables in Production
process.env undefined — database, secrets not loadedYour .env file is in .gitignore and is never deployed. Production servers need environment variables set through a different mechanism.
Option A — set manually on the server
# Create .env manually on server (not in git)
nano /home/ubuntu/myapp/.env
# Add: DATABASE_URL=mongodb+srv://...
# Add: SESSION_SECRET=...
# Add: NODE_ENV=production
# Then load it with dotenv as normal
# require('dotenv').config() in your codeOption B — PM2 ecosystem file
module.exports = {
apps: [{
name: 'my-app',
script: 'server.js',
env_production: {
NODE_ENV: 'production',
PORT: 3000,
DATABASE_URL: 'mongodb+srv://user:pass@cluster.mongodb.net/mydb',
SESSION_SECRET: 'your-secret-here',
}
}]
}
// Start: pm2 start ecosystem.config.js --env productionOption C — platform environment variables
# Heroku
heroku config:set DATABASE_URL=mongodb+srv://...
# Railway / Render
# Dashboard → Variables tab → add each key/value
# DigitalOcean App Platform
# App → Settings → App-Level Environment VariablesNever commit .env to git. Never hardcode production secrets in ecosystem.config.js if that file is committed. Use your platform's secret management.
Wrong Node.js Version on Server
Syntax errors that only occur on older Node versions# Check Node version on server
node --version
# Check what version your app requires
cat package.json | grep '"node"'
# "engines": { "node": ">=20.0.0" }
# If version is wrong — install correct version via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
nvm alias default 20
# Verify
node --version # v20.x.xAdd an engines field to package.json to document required Node version: "engines": { "node": ">=20.0.0" }. This causes npm install to warn if the version is wrong.
Port Permission or Conflict
EADDRINUSE or EACCES on startup# Port already in use
kill -9 $(lsof -ti:3000)
# Permission denied on port 80 — use port 3000+ and nginx instead
# Or grant Node the capability:
sudo setcap 'cap_net_bind_service=+ep' $(which node)
# With PM2 — kill PM2's port before restart
pm2 stop my-app
kill -9 $(lsof -ti:3000)
pm2 start my-appPM2 App Not Starting
PM2 shows errored or stopped statusDiagnose PM2 errors
# See all apps and their status
pm2 list
# See full details of a specific app
pm2 describe my-app
# View logs (most important — shows the actual error)
pm2 logs my-app
pm2 logs my-app --err --lines 100 # errors only
# View logs file directly
cat ~/.pm2/logs/my-app-error.log
# Test by running directly (shows errors in terminal)
pm2 stop my-app
node server.js # run manually to see raw error outputCommon PM2 fixes
# Wrong script path — verify file exists
ls server.js
ls src/index.js
# Fix script path in PM2
pm2 stop my-app
pm2 delete my-app
pm2 start server.js --name my-app
# Or use ecosystem.config.js (recommended)
pm2 start ecosystem.config.js
# Regenerate PM2 startup config
pm2 unstartup
pm2 startup
# (run the printed command as root)
pm2 savePM2 Starts But App Crashes in a Loop
restart_count keeps climbingIf PM2 shows an app as 'online' but it is restarting every few seconds, the app is crashing immediately after start. The process manager brings it back up, it crashes again — a crash loop.
# Check restart count
pm2 list # look at restarts column
# Stop the crash loop — prevent PM2 from restarting
pm2 stop my-app
# Run directly to see the raw error
node server.js
# Common causes of crash loops:
# - Missing DATABASE_URL → MongoServerSelectionError
# - PORT already in use → EADDRINUSE
# - SyntaxError → parsing failure
# - Missing npm install → Cannot find modulemodule.exports = {
apps: [{
name: 'my-app',
script: 'server.js',
max_restarts: 5, // stop trying after 5 crashes
restart_delay: 3000, // wait 3 seconds between restarts
min_uptime: '5s', // must stay up 5s to count as successful
max_memory_restart: '500M',
}]
}App Works Locally But Crashes in Production
Environment differences between local and serverProduction crashes that do not happen locally are caused by environment differences. Work through this checklist systematically:
- NODE_ENV is set to 'production' — some libraries behave differently
- All environment variables set — compare .env.example with production config
- Database connection string is correct — Atlas IP whitelisted for production server IP
- Node.js version matches — check node --version on both machines
- npm install was run after latest deployment
- File permissions correct — app can read/write its required directories
- Memory limit — production server may have less RAM than local machine
// server.js — validate all required env vars at startup
const required = [
'DATABASE_URL',
'SESSION_SECRET',
'PORT',
]
const missing = required.filter(key => !process.env[key])
if (missing.length > 0) {
console.error('Missing required environment variables:', missing)
process.exit(1) // fail fast with clear message
}
console.log('All required env vars present — starting server...')Auto-Start PM2 on Server Reboot
Keep app running after server restarts# Step 1 — generate startup script for your OS
pm2 startup
# Output: [PM2] To setup the Startup Script, copy/paste the following command:
# sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu --hp /home/ubuntu
# ← run that exact command
# Step 2 — save current process list
pm2 save
# [PM2] Saving current process list...
# [PM2] Successfully saved in /home/ubuntu/.pm2/dump.pm2
# Step 3 — verify
sudo reboot
# After reboot: pm2 list ← should show your apps runningAfter any change to your PM2 process list (new apps, deleted apps), run pm2 save again to update what starts on reboot.
Production Deployment Checklist
- 1
git pull (or rsync/deploy files)
Get latest code onto server
- 2
npm ci --omit=dev
Reinstall dependencies
- 3
Verify environment variables
Check all required vars are set
- 4
node --check server.js
Validate syntax without running
- 5
pm2 restart my-app
Restart with new code
- 6
pm2 logs my-app
Watch logs for 30 seconds after restart
- 7
curl http://localhost:3000/health
Hit a health check endpoint
- 8
pm2 save
Persist current process list for reboots
Frequently Asked Questions
Why is my Node.js app not starting on the server?+−
How do I check PM2 logs for why an app is not starting?+−
PM2 shows online but app returns 502 bad gateway?+−
Node.js app works locally but not on server — why?+−
How do I make PM2 start on server reboot?+−
App crashes on production under load but not locally — why?+−
Need Expert Help?
We Deploy & Manage Production Node.js Apps
Softplix builds and deploys full-stack applications. Struggling with production deployment or PM2 setup? We can help configure a stable, zero-downtime deployment.
Talk to an Engineer