Bot Keeps Crashing: Troubleshooting Guide

Quick Diagnosis

When your bot keeps crashing, check these immediately:

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

# Check restart count
pm2 show your-bot | grep "restart time"

# View system resources
free -h && df -h

Common Crash Causes

1. Memory Exhaustion

Symptoms:

• "JavaScript heap out of memory"
• Gradual slowdown before crash
• High restart frequency

Check:

pm2 monit
# Watch memory usage climb over time

Fix - Increase Node.js memory:

pm2 delete your-bot
pm2 start index.js --name your-bot --node-args="--max-old-space-size=2048"
pm2 save

Fix - Enable auto-restart on memory limit:

pm2 start index.js --name your-bot --max-memory-restart 500M

2. Unhandled Promise Rejections

Symptoms:

• "UnhandledPromiseRejectionWarning"
• Random crashes during API calls
• No clear error pattern

Fix - Add global handler:

process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason);
  // Don't exit, just log
});

process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  // Graceful shutdown
  process.exit(1);
});

3. API Connection Failures

Symptoms:

• "ECONNREFUSED" or "ETIMEDOUT"
• Crashes after network issues
• Works fine then suddenly stops

Fix - Add retry logic:

const MAX_RETRIES = 3;
const RETRY_DELAY = 5000;

async function apiCallWithRetry(fn, retries = MAX_RETRIES) {
  try {
    return await fn();
  } catch (error) {
    if (retries > 0 && error.code === 'ECONNREFUSED') {
      await new Promise(r => setTimeout(r, RETRY_DELAY));
      return apiCallWithRetry(fn, retries - 1);
    }
    throw error;
  }
}

4. Discord Gateway Disconnects

Symptoms:

• "Connection to gateway closed"
• "Heartbeat timeout"
• Bot goes offline intermittently

Fix - Configure reconnection:

const client = new Client({
  intents: [...],
  ws: {
    properties: {
      $browser: "Discord iOS" // Sometimes helps with stability
    }
  },
  restTimeOffset: 0,
  failIfNotExists: false
});

client.on('shardDisconnect', (event, shardId) => {
  console.log(`Shard ${shardId} disconnected, reconnecting...`);
});

client.on('shardReconnecting', (shardId) => {
  console.log(`Shard ${shardId} reconnecting...`);
});

5. Rate Limiting

Symptoms:

• "429 Too Many Requests"
• Crashes during high activity
• Works fine with low traffic

Fix - Implement rate limiting:

const rateLimit = new Map();

function checkRateLimit(userId, limit = 5, window = 60000) {
  const now = Date.now();
  const userRequests = rateLimit.get(userId) || [];

  // Remove old requests
  const recent = userRequests.filter(t => now - t < window);

  if (recent.length >= limit) {
    return false; // Rate limited
  }

  recent.push(now);
  rateLimit.set(userId, recent);
  return true; // Allowed
}

6. Disk Space Issues

Symptoms:

• "ENOSPC: no space left on device"
• Log files growing indefinitely
• Crash after running for days

Check:

df -h
du -sh /var/log/*
du -sh ~/.pm2/logs/*

Fix - Configure log rotation:

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 50M
pm2 set pm2-logrotate:retain 7
pm2 set pm2-logrotate:compress true

PM2 Crash Recovery Configuration

Basic Auto-Restart

pm2 start index.js --name your-bot \
  --max-restarts 10 \
  --restart-delay 5000

Advanced Ecosystem File

Create ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'your-bot',
    script: 'index.js',

    // Crash recovery
    max_restarts: 10,
    min_uptime: '10s',
    restart_delay: 5000,

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

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

    // Environment
    env: {
      NODE_ENV: 'production'
    }
  }]
};

Start with:

pm2 start ecosystem.config.js
pm2 save

Crash Analysis

Read Crash Logs

# Last 100 error lines
pm2 logs your-bot --err --lines 100

# Search for specific errors
pm2 logs your-bot | grep -i "error\|exception\|crash"

# Timestamped logs
pm2 logs your-bot --timestamp

Common Error Messages

| Error | Cause | Solution | |-------|-------|----------| | ENOMEM | Out of memory | Increase RAM or limit | | ECONNREFUSED | Network issue | Add retry logic | | ETIMEDOUT | Slow response | Increase timeout | | 429 | Rate limited | Add rate limiting | | ENOSPC | Disk full | Clear logs, add rotation |

Monitoring for Crashes

Set Up Alerts

# Create alert script
cat > /opt/scripts/crash-alert.sh << 'EOF'
#!/bin/bash
WEBHOOK="your-discord-webhook-url"
BOT_NAME="your-bot"

if ! pm2 pid $BOT_NAME > /dev/null 2>&1; then
  curl -H "Content-Type: application/json" \
    -d '{"content":"🔴 Bot crashed and is restarting..."}' \
    $WEBHOOK
fi
EOF

chmod +x /opt/scripts/crash-alert.sh

Schedule Check

crontab -e
# Add:
* * * * * /opt/scripts/crash-alert.sh

Prevention Best Practices

1. Log everything - Can't fix what you can't see
2. Handle all errors - Never let exceptions go uncaught
3. Set memory limits - Prevent runaway consumption
4. Monitor proactively - Know before users do
5. Keep updated - Bugs get fixed in updates

Related Guides

• Bot not responding
• High memory usage
• PM2 errors
• Monitoring setup

Still Crashing?

Our maintenance plans include crash monitoring, automatic recovery, and root cause analysis. Contact us for help.