Discord Bot Crash & Exit Code Troubleshooting

Most Discord bot crashes on Pterodactyl container hosting stem from a predictable set of runtime exceptions: running out of assigned container memory (Exit Code 137), unhandled asynchronous rejections (Exit Code 1), invalid gateway intents, token authentication errors, or Discord API 429 rate limits.

Checking your container's Console tab is always the first diagnostic step. This guide covers how to identify each error signature and resolve it quickly.

---

1. Exit Code 137: Out of Memory (OOM Killer)#

• Symptom: The container suddenly stops, reporting Status: Stopped or Status: Crashed, with console output indicating Killed by OOM killer or Process terminated with exit code 137.
• Root Cause: The bot process exceeded the maximum physical RAM allocated to your container. The Linux kernel immediately terminates the highest-memory process to protect physical node stability.
• Common Triggers:
  • Retaining millions of Discord messages or guild member objects indefinitely without cache sweeping.
  • Memory leaks in event listeners (e.g., adding a new client.on() listener inside another event loop).
  • Processing large image manipulation operations or high-bitrate audio streams directly in memory.
• How to Resolve:
  1. Inspect the memory graph in the Console tab right before the crash. If memory climbed continuously in a diagonal line, your bot has a memory leak.
  2. Implement cache sweepers in discord.js:
     javascript

     Copy

     const client = new Client({
       intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
       sweepers: {
         messages: { interval: 300, lifetime: 900 } // Sweep messages every 5m older than 15m
       }
     });

  3. Turn off unneeded intents (especially GuildMembers and GuildPresences).
  4. If your bot legitimately requires more memory to support its active servers, upgrade your container to a higher RAM tier via the Paid Bot Hosting portal.

---

2. Exit Code 1: Missing Module, Syntax Error, or Unhandled Exception#

• Symptom: The container crashes immediately upon booting with Cannot find module 'xyz' (Node.js) or ModuleNotFoundError: No module named 'xyz' (Python).
• Root Cause: Your code references a third-party library that has not been installed into the container's environment.
• How to Resolve:
  • Node.js: Ensure the package name is present in package.json under "dependencies", then run npm install package-name in the console command bar.
  • Python: Add the package name to requirements.txt in the Files tab, then restart the container to trigger the automatic virtual environment installation.

---

3. Exit Code 4004 / LoginFailure: Invalid Bot Token#

• Symptom: The bot boots, initiates a WebSocket handshake, and exits with Error [TokenInvalid]: An invalid token was provided or discord.errors.LoginFailure: Improper token has been passed.
• Root Cause: The token passed to client.login() or bot.run() is incorrect, has been regenerated, or contains unintentional whitespace or quote marks.
• How to Resolve:
  1. Open the Discord Developer Portal and navigate to your application's Bot tab.
  2. Click Reset Token and copy the freshly generated token.
  3. In your VisiHost control panel, open the Startup tab.
  4. Paste the token into your BOT_TOKEN or DISCORD_TOKEN field without surrounding quotes or leading/trailing spaces.
  5. Restart the container.

---

4. Code 4014 / Disallowed Intents Exception#

• Symptom: The console shows DisallowedIntentsException: Privileged intent provided is not enabled or [DISALLOWED_INTENTS] Privileged intent provided is not enabled.
• Root Cause: Your bot code is requesting privileged gateway intents (such as MessageContent, GuildMembers, or GuildPresences) that have not been enabled in the Discord Developer Portal.
• How to Resolve:
  1. Navigate to the Discord Developer Portal.
  2. Select your application and click the Bot tab on the left sidebar.
  3. Scroll down to the Privileged Gateway Intents section.
  4. Toggle on the specific switches required by your bot (e.g., Message Content Intent, Server Members Intent).
  5. Click Save Changes and restart your container.

---

5. Discord API HTTP 429: Too Many Requests (Rate Limits)#

• Symptom: The bot fails to send messages, role edits, or reactions, logging DiscordAPIError[429]: You are being rate limited.
• Root Cause: Your bot is sending too many requests to a specific Discord API endpoint within a short time window (e.g., spamming message edits or mass-renaming channels in a loop).
• How to Resolve:
  1. Ensure you are using modern library versions (discord.js v14+ or discord.py v2.3+), which have built-in global rate-limit queueing.
  2. Avoid firing API requests inside tight for loops without delays. Add an intentional delay between bulk operations.
  3. If your bot experiences a global IP ban from Discord's Cloudflare edge due to excessive bad requests, leave the container stopped for 15 to 30 minutes to allow the temporary rate-limit cooldown to expire.

---

6. ECONNRESET & WebSocket Disconnections#

• Symptom: The console logs Error: read ECONNRESET, WebSocket connection closed with code 1006, or Heartbeat acknowledged dropped.
• Root Cause: A temporary interruption occurred between your container and Discord's gateway servers, or your bot's main event loop was blocked by a synchronous task, causing it to miss its heartbeat ping deadline.
• How to Resolve:
  • In Node.js, avoid CPU-heavy synchronous functions like fs.readFileSync or large synchronous JSON parsing inside message listeners.
  • In Python, never use time.sleep(); always use await asyncio.sleep().
  • Modern bot libraries will automatically attempt to resume (RESUME) the gateway session. If disconnections persist, verify that your bot is not stuck in a blocking synchronous loop.

---

7. Automatic Crash Restarts & Crash-Loop Protection#

VisiHost containers are continuously managed by our Pterodactyl daemon watchdog:

1. Automatic Recovery: If your bot crashes due to a temporary runtime exception or network hiccup, the daemon will automatically restart your container within seconds.
2. Crash-Loop Guard: If your bot crashes repeatedly (more than 10 times in 60 seconds), the daemon pauses automatic restarts to prevent infinite crash loops and disk log spam.
3. Once you inspect the console and fix the underlying issue, simply click the green Start button to resume normal operations.

---

Frequently Asked Questions (FAQ)#

What does "Heartbeat acknowledged dropped" mean in Discord bot logs?#

This message indicates that your bot missed sending its regular keep-alive ping to Discord's gateway. This almost always happens when a heavy synchronous task (such as a large database query or tight loop) blocks the event loop. Make all heavy functions asynchronous.

What should I do if my bot is stuck in a crash loop?#

The Pterodactyl daemon will temporarily pause restarts if your bot crashes more than 10 times in 60 seconds. Inspect the recent console logs to find the error stack trace, fix the issue in your code, and click the green Start button to resume.

Why do I keep getting Discord 429 rate limit errors?#

Discord limits how many requests your bot can send per second per endpoint. Avoid loops that send hundreds of channel messages or role changes without delays. If your bot is in over 2,500 servers, you must shard your bot to distribute gateway connections.

---

Related Documentation#