Discord Bot Troubleshooting

Reference this guide when customers report Discord bot issues. Common symptoms, causes, and resolutions are organized by category.

Connection & Authentication

Symptom	Possible Cause	Resolution
”Websocket connecting…” stuck	Invalid token	Regenerate token in Discord Developer Portal, update env var
”Disallowed intents” error	Privileged intents not enabled	Enable MESSAGE_CONTENT, GUILD_MEMBERS intents in Developer Portal
Bot exits immediately (code 0)	Missing DISCORD_TOKEN env var	Verify environment variable is set and not empty
”Invalid token” error	Token regenerated elsewhere	Get fresh token from Developer Portal
Bot offline in Discord	Container not running	Check portal status, review startup logs

Token Troubleshooting

1. Verify token format (starts with bot user ID encoded in base64)
2. Ensure no extra whitespace in environment variable
3. Confirm token hasn’t been regenerated since last deployment
4. Check token isn’t from wrong bot application

Intent Verification

Required intents depend on bot functionality:

Feature	Required Intent	Privileged
Message content	MESSAGE_CONTENT	Yes
Member events	GUILD_MEMBERS	Yes
Presence updates	GUILD_PRESENCES	Yes
Basic commands	GUILDS	No
Reactions	GUILD_MESSAGE_REACTIONS	No

Enable privileged intents at: Discord Developer Portal → Bot → Privileged Gateway Intents

Performance Issues

Memory Problems

Symptoms:

• Bot becomes unresponsive
• “Heap out of memory” errors
• Frequent restarts

Solutions:

1. Reduce Discord.js cache sizes
2. Implement data pagination
3. Clear unused variables
4. Upgrade to larger plan
5. Use external caching (Redis)

Cache configuration example:

const client = new Client({
  intents: [...],
  makeCache: Options.cacheWithLimits({
    MessageManager: 25,
    GuildMemberManager: 50,
    PresenceManager: 0
  })
});

CPU Spikes

Symptoms:

• Slow command responses
• Timeouts
• High resource usage in portal

Solutions:

1. Profile code to find bottlenecks
2. Offload heavy operations to workers
3. Implement request queuing
4. Cache expensive computations
5. Upgrade plan for more CPU

Slow Commands

Symptoms:

• “Interaction failed” messages
• Commands timing out
• Users reporting lag

Solutions:

1. Use deferReply() for operations > 3 seconds
2. Cache database queries
3. Optimize API calls
4. Implement pagination for large responses

Defer example:

await interaction.deferReply();
// ... long operation ...
await interaction.editReply('Done!');

Slash Command Issues

Issue	Cause	Fix
Commands not appearing	Not registered	Run registration script with correct token
Wrong server shows commands	Guild vs global registration	Check registration scope
Old commands persist	Cache delay	Wait up to 1 hour for global, restart Discord app
”Unknown interaction”	Handler not implemented	Add interaction handler for command

Registration Script Example

const { REST, Routes } = require('discord.js');
const rest = new REST().setToken(process.env.DISCORD_TOKEN);

// Global commands (up to 1 hour delay)
await rest.put(Routes.applicationCommands(clientId), { body: commands });

// Guild commands (instant, for testing)
await rest.put(Routes.applicationGuildCommands(clientId, guildId), { body: commands });

Audio & Voice Issues

Symptoms:

• No audio playback
• Voice connection drops
• “FFMPEG not found” errors

Solutions:

1. Verify FFmpeg installed:

   • Check with support if system package is available
   • Some nodes include FFmpeg by default

2. Check permissions:

   • Bot needs CONNECT and SPEAK in voice channel
   • Verify role hierarchy allows joining

3. Voice adapter setup:

   const { joinVoiceChannel } = require('@discordjs/voice');
   const connection = joinVoiceChannel({
     channelId: channel.id,
     guildId: guild.id,
     adapterCreator: guild.voiceAdapterCreator
   });

4. Consider Lavalink: For production music bots, external audio servers reduce load

Dependency Issues

Node.js

Error	Cause	Fix
”Cannot find module”	Dependencies not installed	Run npm install
”Module not found”	Wrong import path	Check file exists at path
node-gyp errors	Native module build failed	Use pre-built binaries or request build tools
Version mismatch	Package incompatibility	Check package.json engines, update packages

Python

Error	Cause	Fix
”ModuleNotFoundError”	Package not installed	Run pip install -r requirements.txt
”No module named”	Import path wrong	Check package name vs import name
Wheel build failed	Missing system libraries	Request library installation or use pre-built wheels

Rate Limits

Symptoms:

• 429 errors in logs
• Commands failing intermittently
• “You are being rate limited” messages

Solutions:

1. Implement request queuing
2. Respect X-RateLimit headers
3. Cache frequently accessed data
4. Use bulk operations where possible
5. Add exponential backoff

Rate limit handling:

client.rest.on('rateLimited', (info) => {
  console.log(`Rate limited: ${info.route} for ${info.timeout}ms`);
});

Database Issues

Connection Errors

Error	Cause	Fix
”Connection refused”	Wrong host/port	Verify DATABASE_URL env var
”Access denied”	Wrong credentials	Check username/password
”Too many connections”	Pool exhausted	Implement connection pooling
”Connection timeout”	Network issue	Check if database service is running

SQLite Corruption

Prevention:

• Enable WAL mode
• Schedule graceful restarts
• Regular backups

Recovery:

1. Stop the bot
2. Restore from backup
3. Run integrity check: PRAGMA integrity_check;

Restart Loops

Symptoms:

• Bot continuously restarting
• “Maximum restart attempts reached”
• Rapid console clear/start cycles

Diagnosis:

1. Check console for error message before restart
2. Note the exit code:
   • Code 0: Clean exit, check if bot completes and exits
   • Code 1: Error, check stack trace
   • Code 137: Out of memory (OOM killed)

Solutions:

1. Fix the underlying error in code
2. Increase memory if OOM
3. Disable problematic features via env vars
4. Rollback to last working backup

Diagnostic Commands

Check Node.js Version

node --version

Check Installed Packages

npm list

Memory Usage

node -e "console.log(process.memoryUsage())"

Python Version

python --version

Python Packages

pip list

When to Contact Support

Escalate to hosting support when:

• Suspected infrastructure issues (network, disk, hardware)
• Need system packages installed (FFmpeg, codecs)
• Persistent issues after troubleshooting
• Security concerns
• Billing or account issues

Information to Provide

1. Bot/Server name and ID
2. Timeline of when issue started
3. Recent changes (code, config, updates)
4. Full console output/logs
5. Steps already taken to troubleshoot
6. Steps to reproduce (if known)

Related Documentation

• Discord Bot Overview
• Deployment Guide
• Operations Guide