The discord.js gotchas that cost me a week each

If you're new to bots, start with how to make a Discord bot and how to add a bot to Discord. For ready-to-deploy moderation, see the best Discord moderation bots.

This post is about the production gotchas you only learn after your bot is live in real servers.

I run a service that auto-generates and deploys Discord bots from natural-language descriptions. Over 500 bots are running on it. Most of what I learned came from logs at 3am after someone's bot stopped responding, or a community went silent because of an undocumented Discord behavior.

Here's the list I wish I'd had on day one. Each section is a real failure I've debugged more than once.

The first time I hit this I spent two hours auditing the bot's permission integer. It was correct. The bot still couldn't kick anyone.

The thing nobody puts in big letters: discord.js permissions are gated by role hierarchy. A bot can have the KickMembers permission and still fail to kick anyone whose top role sits at or above the bot's top role.

client.on('interactionCreate', async (interaction) => {
  if (!interaction.isChatInputCommand()) return;
  if (interaction.commandName !== 'kick') return;

  const target = interaction.options.getMember('user');
  const botMember = interaction.guild.members.me;

  if (target.roles.highest.position >= botMember.roles.highest.position) {
    return interaction.reply({
      content: "I can't kick that user — their role is at or above mine.",
      ephemeral: true,
    });
  }

  await target.kick(interaction.options.getString('reason') ?? 'No reason');
  await interaction.reply(`Kicked ${target.user.tag}.`);
});

Fix in Discord: drag the bot's role above the roles it needs to manage in Server Settings, Roles. This is the single most common reason a "working" bot doesn't work.

Slash commands give you exactly 3 seconds to respond. If you call any awaited DB query, third-party API, or LLM before .reply(), you lose that race.

Wrong:

const result = await callLLM(prompt);   // 2.4s
await interaction.reply(result);        // 10062

Right:

await interaction.deferReply();         // buys you 15 minutes
const result = await callLLM(prompt);
await interaction.editReply(result);

The deferred reply pattern is one of those things you need to internalize once and then never get bit by again.

This one is brutal because there's no error. Your bot connects, shows as online, registers commands, and never reads a message.

Two parts:

1. In the Discord Developer Portal, toggle "Message Content Intent" on.
2. In your client config, list it:

import { Client, GatewayIntentBits } from 'discord.js';

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent, // without this, message.content is empty
    GatewayIntentBits.GuildMembers,
  ],
});

If you skip either step, message.content arrives as an empty string and your prefix commands look broken for no apparent reason.

If someone reacts to a message your bot didn't observe being created (anything older than the bot's current session), the event payload is partial. Touching .content returns null until you fetch.

client.on('messageReactionAdd', async (reaction, user) => {
  if (reaction.partial) {
    try { await reaction.fetch(); } catch { return; }
  }
  if (reaction.message.partial) {
    try { await reaction.message.fetch(); } catch { return; }
  }
  // safe to use reaction.message.content now
});

Add the Partials config too:

import { Client, Partials } from 'discord.js';

new Client({
  intents: [/* ... */],
  partials: [Partials.Message, Partials.Channel, Partials.Reaction],
});

You can't fetch them with channel.messages.fetch(). You can't add reactions to them. If you want to update one later, you need the original interaction token, not a message ID:

await interaction.reply({ content: 'Loading…', ephemeral: true });
// later
await interaction.editReply({ content: 'Done.' });

If you serialize the interaction across processes (a queue, a webhook handler, etc.), serialize the token, not the message reference.

If your bot crashes hard without closing the websocket, Discord keeps that session alive on their end for a few minutes. New deploys then count against the 1000/day session start limit, and on cold restarts you can see a window where two instances of your bot post duplicate messages.

async function shutdown(signal) {
  console.log(`[bot] ${signal} received, closing gateway`);
  try { await client.destroy(); } catch {}
  process.exit(0);
}
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT',  () => shutdown('SIGINT'));

process.on('unhandledRejection', (err) => {
  console.error('[bot] unhandled rejection:', err);
  // log and continue
});
process.on('uncaughtException', (err) => {
  console.error('[bot] uncaught:', err);
  shutdown('uncaughtException');
});

If you're running on a container platform that sends SIGTERM before forcibly killing, this single block saves you a class of bugs you'd never spot from a single bot.

The REST client emits a rateLimited event for the soft cases (Discord's per-route bucket warnings). If you log it from day one, you get a free monitoring signal:

client.rest.on('rateLimited', (info) => {
  console.warn('[ratelimit]', {
    route: info.route,
    method: info.method,
    timeToReset: info.timeToReset,
    limit: info.limit,
  });
});

In production these almost always trace back to one bot in a 10k-member server doing something dumb in a loop. They never show up in your error monitoring otherwise.

When you run a few hundred bots, the failure distribution shifts. Probably 30% of "the bot is broken" tickets I've seen trace back to:

• Server admin moved roles around
• User revoked the bot's invite
• The bot got rate-limited because someone scripted 1000 reactions
• Discord shipped a behavior change
• A channel was deleted that the bot was scheduled to post in

Your bot needs to log enough that you can prove which of these happened, fast. A single structured log per important event (action attempted, guild ID, user ID, outcome, latency) gets you 80% of the way there.

I learned most of this the hard way running VibeBot, where users describe a Discord bot in plain English and the system generates and deploys discord.js code for them. The interesting failure mode in that setup is that the LLM-generated code has to handle all eight of these gotchas correctly the first time, because the user never sees the code. The patterns above are exactly what we now bake into every generated bot at the template level.

If you're building a Discord bot from scratch, copy the snippets directly. They're worth a week of debugging each.