Team Hydra Documentation

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.

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. See REST and ratelimits.

Compression warnings

If you see a debug line about zlib, install the optional zlib-sync package for gateway compression. Without it the bot still works, just without compression.

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.