discordjs/discord.js · error · RangeError

Shard ${payload.shardId} does not exist

Error message

Shard ${payload.shardId} does not exist

What it means

In setupThreadEvents, when the parent thread sends a Send payload, the bootstrapper resolves the target shard from its shards Map. If the shard id is unknown it throws a RangeError because the payload cannot be forwarded.

Source

Thrown at packages/ws/src/utils/WorkerBootstrapper.ts:109

						parentPort!.postMessage(response);
						break;
					}

					case WorkerSendPayloadOp.Destroy: {
						await this.destroy(payload.shardId, payload.options);
						const response: WorkerReceivePayload = {
							op: WorkerReceivePayloadOp.Destroyed,
							shardId: payload.shardId,
						};

						parentPort!.postMessage(response);
						break;
					}

					case WorkerSendPayloadOp.Send: {
						const shard = this.shards.get(payload.shardId);
						if (!shard) {
							throw new RangeError(`Shard ${payload.shardId} does not exist`);
						}

						await shard.send(payload.payload);
						break;
					}

					case WorkerSendPayloadOp.SessionInfoResponse: {
						break;
					}

					case WorkerSendPayloadOp.ShardIdentifyResponse: {
						break;
					}

					case WorkerSendPayloadOp.FetchStatus: {
						const shard = this.shards.get(payload.shardId);
						if (!shard) {
							throw new Error(`Shard ${payload.shardId} does not exist`);

View on GitHub (pinned to a81ed8a306)

Solutions

1. Ensure the shard is connected before sending payloads through it
2. Check this.shards.has(shardId) before issuing Send payloads from the parent
3. Guard against concurrent destroy + send operations (await destroy completion before sending)
4. Verify shardIds configuration so the parent only routes to ids owned by this worker

Example fix

// before
await manager.send(7, payload);
// after
const shardIds = await manager.getShardIds();
if (shardIds.includes(7)) {
  await manager.send(7, payload);
}

if (!bootstrapper.shards.has(payload.shardId)) {
  // drop or requeue the payload instead of forwarding
  return;
}

function shardExists(bootstrapper: WorkerBootstrapper, shardId: number): boolean {
  return bootstrapper.shards.has(shardId);
}

try {
  await bootstrapper.send(shardId, payload);
} catch (e) {
  if (e instanceof RangeError && e.message.includes('does not exist')) {
    queue.push(payload); // requeue until shard respawns
  } else throw e;
}

When it happens

Trigger: The parent process sends a WorkerSendPayloadOp.Send message with payload.shardId not present in the worker's shards Map — e.g. a send was queued before/after the shard was spawned or destroyed.

Common situations: Calling manager.send() or shard.send() through the manager while a shard has been destroyed; shard count reduced at runtime; messages racing shard respawn during resharding.

Related errors

• Shard ${shardId} not found
• Shard ${shardId} does not exist
• No worker found for shard ${shardId}
• ShardingProcessExists
• ShardingWorkerExists

AI-assisted analysis of discordjs/discord.js@a81ed8a306 (2026-08-30). Data as JSON: /api/errors/c0e2cd6e800ddf64. Report an issue: GitHub.