Discord error 4010: Invalid shard

The shard array in your Identify payload is invalid. It must be [shard_id, num_shards] where shard_id is in the range 0 to num_shards - 1. Sending a shard ID equal to or greater than the total, a negative value, a non-integer, or a total of 0 results in 4010 and the connection is closed. Discord marks it not reconnectable: retrying with the same payload fails identically.

This is a configuration bug in sharded deployments. Typical examples: an off-by-one where shard IDs are numbered 1..N instead of 0..N-1, an orchestrator that passes the total shard count from one environment and the shard ID from another, environment variables read as strings and concatenated instead of parsed, or a cluster manager that spawned more workers than the configured total.

The error is cheap to reproduce and therefore cheap to test: an integration test that boots one shard with deliberately broken values ([1, 1] is the classic off-by-one, since the only valid ID when num_shards is 1 is 0) catches the whole class before deployment. Orchestrators that scale shard counts at runtime need special care, because every connected shard must agree on the same total; Discord validates each Identify independently, so a rolling redeploy that briefly mixes old and new totals will bounce the shards carrying the stale value.

// WebSocket close frame
code: 4010
reason: "Invalid shard"

// an Identify that triggers it (id equals total)
{ "op": 2, "d": { "token": "...", "intents": 513, "shard": [4, 4], "properties": { ... } } }

Centralize shard configuration in the process that spawns shards and pass both values explicitly to each child; validate them before any connection attempt. Treat the total shard count as a single source of truth stored alongside the deployment, never hard-coded per shard.

The shard-assignment formula and the 2,500-guild ceiling that forces sharding in the first place are on the Discord limits page; if the count is right but the scale is wrong, the close code is 4011.