Discord Bot Troubleshooting

Reference this guide when production bots misbehave. It lists common symptoms, likely causes, and recovery actions.

Connection & Authentication

Symptom	Possible Cause	Fix
Console stuck on “Websocket connecting…”	Invalid token, missing privileged intents, Discord outage	Regenerate the token, ensure MESSAGE_CONTENT/presence intents are approved, check https://discordstatus.com
Bot immediately exits with code 0	Missing env vars, entry file path incorrect	Verify DISCORD_TOKEN exists, update the start command to point to the correct script
Slash commands not showing	Commands not registered, wrong application ID, propagation delay	Run your registration script with the production token, confirm you target the correct guild/global scope, wait a few minutes for propagation

Performance & Resource Issues

• Memory creep: Use heap snapshots or disable large caches; upgrade to a larger plan if memory exceeds 75% after optimizations.
• High CPU: Audio transcoding, large shards, or synchronous code can spike CPU. Offload heavy work to worker queues or scale to Premium.
• Slow commands: Profile DB/HTTP calls, enable caching, and enforce timeouts. Discord requires interactions to respond within 3 seconds (use deferred replies if needed).

Voice & Audio

• Install FFmpeg and libsodium (request via support).
• Ensure the bot has CONNECT + SPEAK permissions and that the voice region matches your audience.
• Prefer discord.js voice adapters or Lavalink-like services if you need centralized audio mixing.

Dependency Problems

• Node-gyp failures: Prebuild binaries locally (npm rebuild --build-from-source) and upload, or request missing build tools.
• pip install errors: Use pip wheel to precompile packages or install system libraries (libffi, libxml2, etc.) via support.
• Outdated libraries: Keep Discord library versions current to avoid API incompatibilities.

Rate Limits & API Errors

• Implement centralized request queues and respect Discord’s X-RateLimit headers.
• For REST-heavy bots, cache results and use bulk operations.
• Log 429 responses with route info so you can identify hotspots quickly.

Watchdog Restart Loops

1. Open the panel console and note the exit code/stack trace.
2. Disable the problematic feature via feature flags or environment variables.
3. Deploy a fix to staging, validate, then promote to production.
4. If urgent, roll back using the panel backup system.

Database & Persistence

• MySQL connection refused: Confirm credentials/env vars, ensure you’re using the provided host/port, and whitelist IPs if necessary.
• SQLite corruption: Restore from the latest backup and reduce unclean shutdowns by enabling scheduled restarts.
• Migration failures: Run migrations locally first; wrap production migrations in try/catch blocks with alerts.

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>

When to Contact Support

• Requiring additional system packages (FFmpeg, libsodium, specific codecs).
• Panel/API access for automation.
• Persistent hardware-level issues (disk, networking).
• Custom plan requirements (GPU inference, multi-region failover).

Collect the following before opening a ticket:

1. Timeline of events.
2. Recent deployment changes.
3. Console logs/traces.
4. Guild IDs or user IDs affected.
5. Steps to reproduce (if known).

Support: support@mambahost.com or Discord https://discord.gg/mambahost