Node.jsPM2Production2026 Updated

Node.js App Not Starting on Server— PM2 & Production Fixed [2026]

Also covers: PM2 app not starting · Node.js app crashing on production

January 20268 min readNode.js · PM2 · Linux

⚡ First Step — Read the Logs

terminal
# 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-app

The 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 logsFix
Cannot find moduleRun npm install — Fix 1
undefined (env variable)Set environment variables — Fix 2
SyntaxError / ReferenceErrorCode error — fix the bug then redeploy
EADDRINUSE: port already in useKill the port — Fix 4
EACCES: permission deniedPort below 1024 — Fix 4
MongoServerSelectionErrorDB env var not set or IP not whitelisted
Exit code 1, no error shownRun node server.js directly to see error
1

Run npm install on the Server

Cannot find module — missing node_modules
2 min

node_modules is in .gitignore and never deployed. After every deployment or git pull, you must run npm install on the server.

terminal — on your 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.js

Add npm install (or npm ci) to your deployment script or CI/CD pipeline so it runs automatically on every deploy.

2

Set Environment Variables in Production

process.env undefined — database, secrets not loaded
5 min

Your .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

terminal — on your 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 code

Option B — PM2 ecosystem file

ecosystem.config.js
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 production

Option 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 Variables

Never commit .env to git. Never hardcode production secrets in ecosystem.config.js if that file is committed. Use your platform's secret management.

3

Wrong Node.js Version on Server

Syntax errors that only occur on older Node versions
5 min
terminal
# 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.x

Add 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.

4

Port Permission or Conflict

EADDRINUSE or EACCES on startup
2 min
terminal
# 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-app
5

PM2 App Not Starting

PM2 shows errored or stopped status
5 min

Diagnose PM2 errors

terminal
# 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 output

Common PM2 fixes

terminal
# 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 save
6

PM2 Starts But App Crashes in a Loop

restart_count keeps climbing
3 min

If 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.

terminal
# 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 module
ecosystem.config.js — limit restart attempts
module.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',
  }]
}
7

App Works Locally But Crashes in Production

Environment differences between local and server
5 min

Production 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
terminal — add startup validation
// 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...')
8

Auto-Start PM2 on Server Reboot

Keep app running after server restarts
3 min
terminal
# 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 running

After 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. 1

    git pull (or rsync/deploy files)

    Get latest code onto server

  2. 2

    npm ci --omit=dev

    Reinstall dependencies

  3. 3

    Verify environment variables

    Check all required vars are set

  4. 4

    node --check server.js

    Validate syntax without running

  5. 5

    pm2 restart my-app

    Restart with new code

  6. 6

    pm2 logs my-app

    Watch logs for 30 seconds after restart

  7. 7

    curl http://localhost:3000/health

    Hit a health check endpoint

  8. 8

    pm2 save

    Persist current process list for reboots

Frequently Asked Questions

Why is my Node.js app not starting on the server?+
The most common causes are: missing node_modules (run npm install), missing environment variables (.env not on server — set them via platform dashboard or manually), wrong Node.js version, port already in use, or a syntax/runtime error. Check logs: pm2 logs or node server.js directly to see the exact error.
How do I check PM2 logs for why an app is not starting?+
Run pm2 logs app-name to see real-time logs. Or pm2 logs app-name --lines 100 for the last 100 lines. For the full error on crash: pm2 describe app-name shows the exit code and restart count.
PM2 shows online but app returns 502 bad gateway?+
Your Node.js app is running but crashed internally — PM2 shows the process but the HTTP server failed. Check pm2 logs for errors inside the app. Usually a missing env variable causes the DB connection to fail on startup.
Node.js app works locally but not on server — why?+
Common differences: different environment variables (database URLs, secrets), different Node.js version, missing node_modules (always run npm install on server), different OS path separators, or less available memory on server.
How do I make PM2 start on server reboot?+
Run: pm2 startup — this prints a command to run as root. Run that command. Then: pm2 save — saves the current process list. On reboot, PM2 automatically restarts all saved processes.
App crashes on production under load but not locally — why?+
Production-only causes: concurrent requests revealing race conditions, memory limits being hit under real traffic, unhandled promise rejections that only occur with real data, or rate limiting from external APIs. Enable error tracking (Sentry) to capture crash context.

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