Fix Discord Bot Connection Issues

Quick Diagnosis

# Check if bot process is running
pm2 status

# View connection errors
pm2 logs your-bot | grep -i "discord\|gateway\|connect"

# Test Discord API
curl -I https://discord.com/api/v10/gateway

Common Connection Issues

1. Invalid Token

Symptoms:

• "An invalid token was provided"
• Bot immediately goes offline
• 401 errors in logs

Check:

pm2 logs your-bot | grep -i "token\|401\|invalid"

Fix:

1. Go to Discord Developer Portal
2. Select your application → Bot
3. Click "Reset Token"
4. Copy new token
5. Update .env:

DISCORD_TOKEN=new-token-here

6. Restart: pm2 restart your-bot

2. Gateway Disconnect

Symptoms:

• Bot shows offline randomly
• "Gateway disconnected" in logs
• Works then stops

Check:

pm2 logs your-bot | grep -i "gateway\|disconnect\|close"

Fix:

Most bots auto-reconnect. If persistent:

1. Check Discord status: discordstatus.com
2. Add reconnection handling:

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

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

3. Restart bot: pm2 restart your-bot

3. Missing Intents

Symptoms:

• Bot connects but can't see messages
• "Missing intent" error
• No response to commands

Check:

pm2 logs your-bot | grep -i "intent"

Fix:

1. Enable intents in Developer Portal:

   • Go to Bot section
   • Enable "Message Content Intent"
   • Enable other required intents

2. Update code:

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
    GatewayIntentBits.DirectMessages
  ]
});

4. Rate Limited

Symptoms:

• Bot works then stops
• "Rate limited" or 429 errors
• Slow responses

Check:

pm2 logs your-bot | grep -i "rate\|429\|limit"

Fix:

• Reduce message frequency
• Add delays between actions
• Check for loops sending many messages

// Add delay between messages
await message.reply('Response 1');
await new Promise(r => setTimeout(r, 1000));
await message.reply('Response 2');

5. Network Firewall

Symptoms:

• Bot can't connect at all
• Timeout errors
• Works locally but not on VPS

Check:

# Test connection
curl -I https://discord.com

# Check firewall
sudo ufw status

Fix:

# Allow outbound HTTPS
sudo ufw allow out 443/tcp
sudo ufw reload

6. DNS Issues

Symptoms:

• "getaddrinfo ENOTFOUND"
• Can't resolve Discord addresses

Check:

nslookup discord.com
ping discord.com

Fix:

# Use Google DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 8.8.4.4" | sudo tee -a /etc/resolv.conf

Or configure in /etc/systemd/resolved.conf:

[Resolve]
DNS=8.8.8.8 8.8.4.4

7. Bot Verification Required

Symptoms:

• Bot in 75+ servers can't connect
• Verification error in logs

Fix: Bots in 75+ servers need verification:

1. Go to Developer Portal
2. Navigate to App Verification
3. Complete verification process

8. WebSocket Errors

Symptoms:

• "WebSocket was closed"
• Connection drops frequently

Check:

pm2 logs your-bot | grep -i "websocket\|ws"

Fix:

const client = new Client({
  intents: [...],
  ws: {
    properties: {
      browser: "Discord iOS"  // Sometimes helps
    }
  }
});

Diagnostic Commands

Full Connection Test

#!/bin/bash
echo "=== Discord Connection Diagnostic ==="

echo -e "\n1. Bot Process:"
pm2 status | grep your-bot

echo -e "\n2. Network Test:"
curl -s -o /dev/null -w "Discord API: %{http_code}\n" https://discord.com/api/v10/gateway

echo -e "\n3. DNS Test:"
nslookup discord.com | head -6

echo -e "\n4. Recent Errors:"
pm2 logs your-bot --err --lines 10

Check Discord Status

Before debugging, verify Discord is working:

• discordstatus.com
• Twitter @discord

Prevention

Reconnection Handling

client.on('shardError', (error, shardId) => {
  console.error(`Shard ${shardId} error:`, error);
});

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

// Graceful shutdown
process.on('SIGINT', () => {
  client.destroy();
  process.exit(0);
});

Health Monitoring

Set up alerts for disconnection:

# Check every minute
*/1 * * * * pm2 status | grep -q "online" || curl -X POST webhook-url

Use PM2 Correctly

pm2 start bot.js --name your-bot \
  --max-restarts 10 \
  --restart-delay 5000 \
  --exp-backoff-restart-delay 100

Error Message Reference

| Error | Meaning | Solution | |-------|---------|----------| | TOKEN_INVALID | Wrong token | Regenerate token | | DISALLOWED_INTENTS | Missing intent permission | Enable in Developer Portal | | 4014 | Disallowed intent | Enable privileged intents | | 4004 | Invalid token | Check/regenerate token | | 4008 | Rate limited | Reduce reconnection attempts | | 4009 | Session timeout | Will auto-reconnect |

Related Guides

• Discord permissions
• OpenClaw Discord setup
• Bot crashes

Need Help?

Discord connection issues can be tricky. Our support plans include rapid troubleshooting for connection problems.