Skip to content
Mamba Host Docs

Discord Bot Troubleshooting

Use this guide when your Discord bot misbehaves. Work through the sections in order and gather logs before contacting support.

Connection & Authentication

Section titled “Connection & Authentication”
SymptomPossible CauseSolution
Console stuck on “Connecting…”Invalid token, missing intents, Discord outageRegenerate token, ensure intents are approved, check discordstatus.com
Bot exits immediately (code 0)Missing env vars, wrong entry file pathVerify DISCORD_TOKEN exists, update start command
Slash commands not showingCommands not registered, wrong app IDRun registration script with production token, wait for propagation

Performance Issues

Section titled “Performance Issues”

Memory Problems

Section titled “Memory Problems”

  1. Use heap snapshots to identify memory leaks

  2. Disable large caches or move them to Redis

  3. Reduce shard count if memory per shard is high

  4. Upgrade plan if memory exceeds 75% after optimizations

High CPU Usage

Section titled “High CPU Usage”

  1. Profile your code for CPU-intensive operations

  2. Offload audio transcoding to dedicated workers

  3. Reduce sync operations in favor of async patterns

  4. Scale to Premium for CPU-heavy workloads

Slow Commands

Section titled “Slow Commands”

  1. Profile database and HTTP calls for bottlenecks

  2. Enable caching for frequently accessed data

  3. Use deferred replies for operations taking > 3 seconds

  4. Enforce timeouts on external API calls

Voice & Audio Issues

Section titled “Voice & Audio Issues”

  1. Request FFmpeg and libsodium from support if not installed

  2. Verify bot permissions — needs CONNECT and SPEAK

  3. Check voice region matches your audience

  4. Consider Lavalink for centralized audio mixing

ProblemSolution
No audio outputConfirm FFmpeg installed, check bot permissions
Audio stutteringReduce concurrent voice connections, upgrade CPU
Voice channel errorsVerify bot has permission to join/speak

Dependency Problems

Section titled “Dependency Problems”

Node.js Issues

Section titled “Node.js Issues”
ProblemSolution
node-gyp failuresPre-build binaries locally and upload
Module not foundRun npm install in panel console
Outdated Discord.jsUpdate to avoid API incompatibilities

Python Issues

Section titled “Python Issues”
ProblemSolution
pip install errorsUse pip wheel to pre-compile packages
Missing system librariesRequest libffi, libxml2, etc. via support
Wheel build failuresPre-build locally and upload

Rate Limits & API Errors

Section titled “Rate Limits & API Errors”

  1. Implement request queuing with exponential backoff

  2. Respect X-RateLimit headers from Discord

  3. Cache API results to reduce redundant calls

  4. Use bulk operations where available

  5. Log 429 responses with route info to identify hotspots

Watchdog Restart Loops

Section titled “Watchdog Restart Loops”

  1. Check console for exit code and stack trace

  2. Disable problematic features via environment variables

  3. Test fix in staging before promoting to production

  4. Roll back using panel backups if urgent

Common Exit Codes

Section titled “Common Exit Codes”
CodeMeaningAction
0Clean exit (possibly early)Check for missing token or config
1General errorReview stack trace in logs
137Out of memory (OOM killed)Optimize memory or upgrade plan

Database Issues

Section titled “Database Issues”
ProblemSolution
MySQL connection refusedVerify credentials and host/port in env vars
SQLite corruptionRestore from backup, reduce unclean shutdowns
Migration failuresRun migrations locally first, wrap in try/catch

Quick Diagnostic Checklist

Section titled “Quick Diagnostic Checklist”

Before contacting support, verify:

  • Token is valid and not expired
  • Required intents are enabled in Discord Dev Portal
  • Environment variables are set correctly
  • Dependencies are installed (npm install / pip install)
  • Entry file path matches start command
  • No rate limit errors in logs
  • Checked discordstatus.com for outages

When to Contact Support

Section titled “When to Contact Support”

Gather this information before opening a ticket:

  1. Timeline — When did the issue start?

  2. Recent changes — Deployments, config updates, library upgrades

  3. Console logs — Error messages and stack traces

  4. Guild/user IDs — Affected guilds or users

  5. Steps to reproduce — If known

Request Support For

Section titled “Request Support For”
  • System package installation (FFmpeg, libsodium, codecs)
  • Panel/API access for automation
  • Persistent hardware issues
  • Custom plan requirements (GPU, multi-region)

Incident Response Template

Section titled “Incident Response Template”
Incident: <Short description>
Detected: <Timestamp + monitoring source>
Impact: <Commands failing / downtime length / affected guilds>
Immediate Action: <Scale, rollback, disable feature>
Root Cause: <Once found>
Follow-up Tasks: <Testing, automation, docs>
Section titled “Helpful Links”
Discord Bot Overview Platform features and architecture
Deployment Guide Upload code and configure secrets
Operations & Scaling Monitoring, sharding, and cost management
Panel Guide Learn panel features

Need Help?

Section titled “Need Help?”