Tech Setup
Discord Bots

Fix Discord Bot Startup Crash: Missing Intents Explained

Tech Setup5 min read
TS

Tech Setup

Published August 21, 2026 · Editorial policy

Fix Discord Bot Startup Crash: Missing Intents Explained

Your Node.js or Python Discord bot crashes immediately upon startup with an unhandled exception or a vague error pointing toward privileged gateway intents. This usually hits you right after wiring up a new feature like welcoming users or tracking member counts, leaving your terminal cluttered with stack traces from discord.js or discord.py. By the end of this guide, you will have correctly registered your gateway intents in both your bot’s code and the Discord Developer Portal, getting your bot online without throwing permission crashes.

Quick TL;DR Fix

If you are in a rush and just want the bot to boot up, you need to fix two things simultaneously:

  1. Enable the toggle switches inside the Discord Developer Portal under your application's Bot settings.
  2. Pass the exact matching GatewayIntentBits (JavaScript) or Intents (Python) into your client initialization constructor in code.

Skipping either side of this equation results in an immediate startup failure or a silent drop of gateway events.

Why Your Bot Crashes on Startup

Discord changed how bots receive data to comply with privacy standards and scaling limits. Instead of sending every event to every connected bot by default, Discord now requires you to explicitly declare which events your bot needs. These declarations are called Gateway Intents.

When your code attempts to instantiate a client and subscribe to events like GuildMembers or MessageContent without telling the Discord API you are allowed to listen to them, the gateway connection drops. Depending on your library version, you will see errors like:

  • DisallowedIntents: Privileged intent provided is not enabled or whitelisted.
  • [GatewayIntentBits.GuildMembers] is not a valid intent or requires verification.

To fix this, you must enable the intents in the Discord Developer Portal first, and then mirror those exact selections in your codebase.

Step 1: Enable Intents in the Developer Portal

Log into the Discord Developer Portal and navigate to your application dashboard.

  1. Click on your application's name to open the settings panel.
  2. In the left-hand sidebar, click on the Bot tab.
  3. Scroll down past the username and token section until you reach the Privileged Gateway Intents section.

Toggling Privileged Intents

You will see three distinct toggles here. Enable the ones your code requires:

  • Presence Intent: Required if your bot tracks user statuses, custom activities, or online presence.
  • Server Members Intent: Required if your bot tracks member joins, leaves, role updates, or fetches the member list of a guild. This is the most common culprit for startup crashes.
  • Message Content Intent: Required if your bot reads the actual text body of messages (essential for traditional prefix commands like !ping).

Click Save Changes at the bottom of the page. If you miss this step, changing your code alone will not prevent the crash.

Step 2: Configure Intents in Your Codebase

Once the portal is updated, you must configure your bot framework to request these intents during initialization.

For Node.js (discord.js v14+)

In discord.js v14, intents are strictly enforced. Open your main entry file (usually index.js or bot.js) and import GatewayIntentBits from the discord.js package. Pass an array of required bits into the Client constructor.

const { Client, GatewayIntentBits } = require('discord.js');

const client = new Client({
    intents: [
        GatewayIntentBits.Guilds,
        GatewayIntentBits.GuildMessages,
        GatewayIntentBits.MessageContent, // Matches Developer Portal toggle
        GatewayIntentBits.GuildMembers   // Matches Developer Portal toggle
    ]
});

client.once('ready', () => {
    console.log(`Logged in as ${client.user.tag}!`);
});

client.login(process.env.DISCORD_TOKEN);

Run your bot using your standard execution command:

node index.js

Expected output:

Logged in as MyTestBot#1234!

For Python (discord.py v2.0+)

In discord.py, you configure intents using the Intents class. You can enable default intents and then explicitly flag the privileged ones to True.

import discord

intents = discord.Intents.default()
intents.message_content = True  # Matches Developer Portal toggle
intents.guilds = True
intents.members = True          # Matches Developer Portal toggle

client = discord.Client(intents=intents)

@client.event
async def on_ready():
    print(f'Logged in as {client.user}')

client.run('YOUR_BOT_TOKEN')

Run your Python script:

python bot.py

Expected output:

Logged in as MyTestBot#1234

If This Doesn't Work: Common Failure Points

If your bot still crashes or refuses to process events after following the steps above, check these three common friction points:

1. Bot Verification and Scale Limits

If your bot is added to 100 or more servers, privileged intents (Server Members and Presence) require your application to go through Discord's official app verification process. For bots under 100 servers, simply toggling the switch in the Developer Portal is enough. If you crossed the 100-server threshold without verification, the API will reject your connection attempt.

2. Mismatched Intent Flags

A frequent mistake is enabling MessageContent in the Developer Portal but forgetting to add GatewayIntentBits.MessageContent (or intents.message_content = True) in your code. Both sides must match. If your code requests an intent that isn't toggled in the portal, the API throws an error.

3. Using Outdated Library Versions

If you are following tutorials written for discord.js v12 or discord.py v1.x, the syntax for intents will differ or might not be strictly enforced. Upgrade your dependencies to the latest stable versions to ensure full compatibility with modern gateway requirements:

# For Node.js
npm install discord.js@latest

# For Python
pip install --upgrade discord.py

Preventing Future Startup Issues

As your bot grows, you will inevitably add features that require new data streams from Discord. To keep your startup clean and avoid unexpected crashes, adopt these best practices:

  • Audit your intents: Only request the intents your bot actually uses. Requesting all intents (often called "ALL_INTENTS") is discouraged by Discord and can trigger security flags or rate limits if your bot scales.
  • Use environment variables: Never hardcode your bot token alongside your intent configurations. Use a .env file managed by dotenv (Node.js) or python-dotenv (Python) to keep credentials secure.
  • Handle gateway warnings: Listen to client error events in your code to catch gateway disconnects before they crash the entire process.

Related articles