When and how to shard a large Discord bot

A small bot connects to Discord once and handles every server it is in. As it grows, that single connection becomes a limit. Discord's answer is sharding: splitting your bot's work across several connections, each looking after a slice of its servers. This guide explains when you need it, how it works and what changes in how you write and host your bot.

What sharding is

A shard is one connection to Discord's gateway that receives events for a subset of your servers. Which servers go to which shard is decided by a fixed formula based on the server's ID:

shard_id = (guild_id >> 22) % total_shards

You do not need to calculate it by hand. Your library does. What matters is that a given server always lands on the same shard while the number of shards stays the same.

When you need it

• At 2,500 servers, it is mandatory. Discord refuses to let a single connection handle more than that, so a bot that grows past the limit stops connecting until it shards.
• Well before that, it can help. Many developers start sharding at about 1,000 servers, because a single connection gets slow to start and heavy on memory.

If your bot is in a few hundred servers, you do not need to think about this yet. Do it when your growth makes it necessary, not early.

How libraries handle it

Library	Option	What it does
discord.js	ShardingManager	Runs each shard as its own process, managed by a parent
discord.js	Internal sharding	Runs shards inside a single process
discord.py	AutoShardedClient or AutoShardedBot	Handles shards in one process, with an automatic count

The simplest path in Python is switching to the auto-sharded class, which asks Discord how many shards are recommended and starts them. In Node.js, the sharding manager launches child processes, which gives more isolation and uses more memory.

What changes in your code

Sharding is easy to turn on and harder to live with, because your bot's memory is no longer shared:

• Caches are per shard. A server's data lives in the shard that owns it. Code that assumes all servers are in one place breaks.
• Global counts need care. To show total members across all servers, you must ask each shard and add up the results. Libraries have helpers, such as discord.js broadcastEval or fetchClientValues.
• Direct messages go to shard 0. Remember this if your bot handles DMs.
• Shared state needs a shared store. Things like cooldowns or counters kept in memory will differ per shard. A database or a store such as Redis keeps them consistent. See How to use a database with your Discord bot.
• Tasks must not run twice. A scheduled job that posts a daily message would run on every shard unless you restrict it to one.

Hosting a sharded bot

Sharding increases what your bot needs:

• Memory. Each process or shard has its own overhead, and caches for its servers. Plan more than the single-shard figure. Hosting resource sizing for Discord bots gives a method.
• CPU. More events are handled at once, though spread across cores in process-based sharding.
• Start-up time. Shards start one after another, because Discord limits how quickly new sessions may be opened, so a big bot takes a while to come fully online.

Because of that start-up delay, restarts are expensive for large bots. Restart less often, and avoid crash loops, which also burn through your daily session allowance. See How to handle Discord rate limits.

Choosing a shard count

Let the library ask Discord for the recommended number, until you have a reason to override it. Discord suggests about one shard per 1,000 servers. Changing the number later means every server may move to a different shard, so do it deliberately, when the bot is restarting anyway.

Testing before you need it

You can test sharding with a small number, such as two shards on a tiny bot, to make sure your code handles it. Do it on a test bot, not the live one. Look for code that reads caches directly, sums values or sends scheduled messages.

Troubleshooting

• Only some servers respond. A shard has crashed or has not connected. Check the logs for the shard number.
• Slash commands fail intermittently. A shard is overloaded, or a command waits too long. See the three second rule in the slash commands guide.
• Memory keeps climbing. Caching is too generous. Reduce what the library keeps.
• Duplicate messages. A scheduled task is running on every shard.

For reading and keeping logs, see Logging and monitoring your Discord bot.

---

Still stuck? Open a ticket on Discord - run /ticket in any channel, pick a department, and include your Server ID or Invoice ID so we can jump straight in.