PM2 Process Errors and Solutions

Common PM2 Errors

Error: "spawn ENOENT"

Cause: Node.js or script file not found

Check:

# Verify Node.js is installed
which node
node --version

# Verify script exists
ls -la index.js

Fix:

# If node not found, reinstall
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# If wrong path, use absolute path
pm2 start /opt/your-bot/index.js --name your-bot

Error: "Script not found"

Cause: Wrong working directory or file path

Check:

pm2 show your-bot | grep "script path"

Fix:

# Delete and restart with correct path
pm2 delete your-bot
cd /opt/your-bot
pm2 start index.js --name your-bot
pm2 save

Error: "EACCES: permission denied"

Cause: Insufficient permissions on files or directories

Check:

ls -la /opt/your-bot/

Fix:

# Fix ownership
sudo chown -R $USER:$USER /opt/your-bot

# Fix permissions
chmod -R 755 /opt/your-bot
chmod 644 /opt/your-bot/*.js

Error: "Cannot find module"

Cause: Dependencies not installed or node_modules corrupted

Check:

ls -la node_modules/

Fix:

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Restart PM2
pm2 restart your-bot

Error: "ENOMEM" / Out of Memory

Cause: Server ran out of RAM

Check:

free -h
pm2 monit

Fix:

# Increase swap space
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Add to fstab for persistence
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# Limit Node.js memory
pm2 delete your-bot
pm2 start index.js --name your-bot --max-memory-restart 500M

Startup Issues

PM2 Not Starting on Boot

Check:

pm2 startup
# Follow the command it outputs

Fix:

# Generate startup script
pm2 startup systemd -u $USER --hp $HOME

# Save current processes
pm2 save

# Verify
systemctl status pm2-$USER

Process Stuck in "Launching"

Cause: Script has syntax error or crashes immediately

Check:

# Try running directly
node index.js

Fix:

# Check for syntax errors
node --check index.js

# View PM2 error logs
pm2 logs your-bot --err --lines 50

Restart Loop (Restarting Rapidly)

Cause: Script crashes immediately after starting

Check:

pm2 show your-bot | grep "restarts"
pm2 logs your-bot --err

Fix:

# Add delay between restarts
pm2 delete your-bot
pm2 start index.js --name your-bot --restart-delay 5000

# Set minimum uptime before counting as "started"
pm2 start index.js --name your-bot --min-uptime 10000

Configuration Issues

Environment Variables Not Loading

Check:

pm2 show your-bot | grep "environment"

Fix - Method 1: Ecosystem file

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'your-bot',
    script: 'index.js',
    env: {
      NODE_ENV: 'production',
      DISCORD_TOKEN: 'your-token',
    }
  }]
};

pm2 start ecosystem.config.js

Fix - Method 2: .env file with dotenv

// At top of index.js
require('dotenv').config();

Logs Not Appearing

Check:

pm2 logs your-bot
ls -la ~/.pm2/logs/

Fix:

# Clear and reset logs
pm2 flush

# Restart with explicit log files
pm2 start index.js --name your-bot \
  --output /opt/your-bot/logs/out.log \
  --error /opt/your-bot/logs/error.log

PM2 Config Not Applied

Check:

pm2 show your-bot
cat ecosystem.config.js

Fix:

# Delete and restart from config
pm2 delete your-bot
pm2 start ecosystem.config.js
pm2 save

PM2 Commands Reference

Basic Commands

# Start/stop/restart
pm2 start your-bot
pm2 stop your-bot
pm2 restart your-bot

# Delete process
pm2 delete your-bot

# List all processes
pm2 list

# Show details
pm2 show your-bot

# View logs
pm2 logs your-bot
pm2 logs your-bot --err
pm2 logs your-bot --lines 100

Monitoring

# Real-time dashboard
pm2 monit

# One-time status
pm2 status

# JSON output
pm2 jlist

Maintenance

# Clear logs
pm2 flush

# Update PM2
npm install -g pm2@latest
pm2 update

# Save process list
pm2 save

# Resurrect saved processes
pm2 resurrect

Best Practices Ecosystem File

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'your-bot',
    script: 'index.js',
    cwd: '/opt/your-bot',

    // Instances (use 1 for Discord bots)
    instances: 1,

    // Restart behavior
    autorestart: true,
    max_restarts: 10,
    min_uptime: '10s',
    restart_delay: 5000,

    // Memory management
    max_memory_restart: '500M',
    node_args: '--max-old-space-size=1024',

    // Logging
    output: './logs/output.log',
    error: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss',
    merge_logs: true,

    // Environment
    env: {
      NODE_ENV: 'production'
    },

    // Watch for changes (development only)
    watch: false,
    ignore_watch: ['node_modules', 'logs']
  }]
};

Debugging Steps

Step 1: Check Process Status

pm2 list
pm2 show your-bot

Step 2: View Logs

pm2 logs your-bot --lines 100
pm2 logs your-bot --err --lines 50

Step 3: Test Manually

pm2 stop your-bot
cd /opt/your-bot
node index.js
# Watch for errors

Step 4: Check System Resources

free -h
df -h
top

Step 5: Fresh Start

pm2 delete all
pm2 kill
pm2 start ecosystem.config.js
pm2 save

Related Guides

• Bot crashes
• Memory issues
• Monitoring setup
• Install OpenClaw

Need Help?

PM2 issues can be tricky. Our maintenance plans include process management and monitoring.