Troubleshooting

A checklist for the most common problems, with the fix.

A checklist for the most common problems, with the fix.

The bot will not log in

  • Invalid token: the token must include the Bot prefix: `Bot ${process.env.DISCORD_TOKEN}`. Re-copy the token from the portal if unsure.
  • Gateway closes with 4014: you requested a privileged intent (GuildPresences, GuildMembers, or MessageContent) that is not enabled on the application's portal page. Enable it or remove it from intents.
  • Nothing happens, no error: make sure you call connect() and that you have an error listener so failures are visible.

The bot logs in but does nothing

  • You are not subscribed to the right intent. To see messages you need GuildMessages (and MessageContent to read their text). See Intents.
  • The event name is wrong. Check spelling against Events.

Slash commands missing

  • Use a DEV_GUILD while developing for instant updates; global commands cache for up to an hour.
  • Confirm deployCommands() (or a bulk-edit call) runs after ready and does not throw.
  • Confirm the bot was invited with the applications.commands scope.

"Unknown interaction" / "already acknowledged"

Respond exactly once, within three seconds. defer() first for slow work; use deferUpdate + editParent for components. See Errors.

If fast handlers still hit 10062 Unknown interaction during click storms on a busy bot, upgrade to Athena 4.4.0 or newer. Earlier versions sent every ack in the process through one ratelimit bucket, so acks queued behind each other until the 3 second window ran out.

50027 Invalid Webhook Token long after a click

A followup or edit failed with 50027 many minutes after the interaction. On versions before 4.5.0, a followup that hit a 429 (followups share a channel's webhook budget, so many followups into one channel are throttled) was retried until the 15 minute interaction token expired. From 4.5.0 it rejects right away with the 429 itself (DiscordHTTPError, code 429) when a retry would land past that deadline. Catch it and send fewer followups, for example by editing one message instead. See REST and ratelimits.

Decorator error on @SlashCommand

Add "experimentalDecorators": true to compilerOptions in tsconfig.json.

Memory keeps climbing

  • Lower messageLimit, disable unused caches with NullCollection, cap big caches with LRUCollection. See Caching and memory.
  • Turn off GuildPresences if you do not use presence.
  • At cluster scale, offload to Redis. See Scaling to millions.

Ratelimited or 429s

Always await REST calls. Prefer bulk endpoints. Athena handles 429 retries automatically; persistent 429s usually mean a bug such as an unbounded retry loop in your own code. Each 429 also emits a warn naming the route (throttled to one per route per 10 seconds), which tells you where to look. To stop a request from retrying forever, set rest.maxRatelimitRetries. See REST and ratelimits.

Compression or WebSocket warnings

Compression and the WebSocket transport are built in; there is nothing to install. A warn that zstd is unavailable means the runtime lacks node

zstd support (Node older than 22.15) and Athena fell back to zlib-stream; upgrade Node. An error telling you to install ws means the ws transport was selected (custom options.ws or gateway: { transport: 'ws' }) without the optional package; run npm install ws.

Unexpected end of JSON input errors after a disconnect

A burst of these error events right after a shard disconnects (often during a large boot) came from gateway messages still queued for decompression when the socket closed. Upgrade to Athena 4.6.0 or newer, which discards that backlog (the resume replays it). The same release stops shards from repeatedly resuming at boot because a heartbeat ACK was stuck behind the backlog.

Channels named ___hidden___

Your bot cannot view that channel, and Discord sent it obfuscated (mandatory from 2026-11-16). Check channel.obfuscated rather than the name, skip those channels in lists and logs, and do not rely on their permissions or metadata.

presenceUpdate never fires

Upgrade to Athena 4.8.0 or newer. In 4.7.0 and earlier every presence update failed with Missing object id, so the event never fired and cached members kept their old status. Also check that the GuildPresences privileged intent is enabled on the portal and in intents.

Reconnect loops after an outage

Stagger reconnects with a randomised reconnectDelay. Check that your token and intents are valid and your host clock is roughly correct (large clock drift triggers warnings).

Still stuck

  • Subscribe to debug temporarily to see gateway and REST activity.
  • Subscribe to rawREST to inspect a failing request's method, URL, and status.
  • Check the FAQ and Errors.