The Discord.js gotchas that cost me a week each (so they don't have to cost you one)

I run an AI Discord bot builder that's deployed 500+ live bots over the last year. The service takes a plain-English description, generates discord.js code, and ships the container to production in under 30 seconds.

That sounds clean. It is not clean.

Most of what I learned came from logs at 3am after someone's bot stopped responding to messages, or a community went silent because of an undocumented Discord behavior. Here's the list I wish I'd had on day one.

1. Missing Permissions (50013) is usually about role position, not permissions

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 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.

1. Unknown Interaction (10062) is a 3-second race

Slash commands give you exactly 3 seconds to respond. If you call any awaited DB query, third-party API, or LLM before.reply(), you'll 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.

1. Intent flags are silent killers

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.

1. Reactions and edits on old messages are partial

If someone reacts to a message your bot didn't observe being created (anything older than the bot's 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],
});

1. Ephemeral replies don't behave like normal messages

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

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

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

1. Process crashes leave gateway sessions hanging

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'll see a brief 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);
// don't crash — log and continue
});
process.on('uncaughtException', (err) => {
console.error('[bot] uncaught:', err);
// do crash, but cleanly
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.

1. Rate limits aren't always 429s

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.

1. The biggest one: most production failures aren't bugs in your code

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:

• The server admin moved roles around
• The user revoked the bot's invite
• The bot was 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 quickly. 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.gg, where users describe a Discord bot in 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 above directly. They're worth a week of debugging each.