discordjs/discord.js · error · DiscordjsError

ShardingShardMiscalculation

ShardingShardMiscalculation

Error message

ShardingShardMiscalculation

What it means

ShardingShardMiscalculation is thrown by ShardClientUtil.shardIdForGuildId() when calculateShardId() returns a negative shard index for the given guildId and shardCount. A negative result means the inputs are invalid (negative shardCount or malformed id math), so the library refuses to return a bogus shard id.

Source

Thrown at packages/discord.js/src/sharding/ShardClientUtil.js:261

        'Multiple clients created in child process/worker; only the first will handle sharding helpers.',
      );
    } else {
      this._singleton = new this(client, mode);
    }

    return this._singleton;
  }

  /**
   * Get the shard id for a given guild id.
   *
   * @param {Snowflake} guildId Snowflake guild id to get shard id for
   * @param {number} shardCount Number of shards
   * @returns {number}
   */
  static shardIdForGuildId(guildId, shardCount) {
    const shard = calculateShardId(guildId, shardCount);
    if (shard < 0) throw new DiscordjsError(ErrorCodes.ShardingShardMiscalculation, shard, guildId, shardCount);
    return shard;
  }

  /**
   * Increments max listeners by one for a given emitter, if they are not zero.
   *
   * @param {Worker|ChildProcess} emitter The emitter that emits the events.
   * @private
   */
  incrementMaxListeners(emitter) {
    const maxListeners = emitter.getMaxListeners();
    if (maxListeners !== 0) {
      emitter.setMaxListeners(maxListeners + 1);
    }
  }

  /**
   * Decrements max listeners by one for a given emitter, if they are not zero.

View on GitHub (pinned to a81ed8a306)

Solutions

1. Validate shardCount is a positive integer before calling (Number.isInteger(count) && count > 0)
2. Validate guildId matches /^\d{17,20}$/ before calling
3. Use manager.shardCount (or ShardClientUtil.shardCount) instead of hand-rolled config values
4. Sanitize user-supplied ids with SnowflakeUtil or BigInt parsing before computing the shard id

Example fix

// before
const shardId = ShardClientUtil.shardIdForGuildId(guildId, Number(process.env.SHARD_COUNT));
// after
const shardCount = Number(process.env.SHARD_COUNT);
if (!Number.isInteger(shardCount) || shardCount <= 0) throw new Error('Invalid SHARD_COUNT');
if (!/^\d{17,20}$/.test(guildId)) throw new Error('Invalid guild id');
const shardId = ShardClientUtil.shardIdForGuildId(guildId, shardCount);

function isValidGuildShardInput(guildId, shardCount) {
  return /^\d{17,20}$/.test(String(guildId)) && Number.isInteger(shardCount) && shardCount > 0;
}
if (isValidGuildShardInput(guildId, shardCount)) {
  const shardId = ShardClientUtil.shardIdForGuildId(guildId, shardCount);
}

function isSnowflake(value) { return typeof value === 'string' && /^\d{17,20}$/.test(value); }
function isValidShardCount(n) { return Number.isInteger(n) && n > 0; }

let shardId;
try {
  shardId = ShardClientUtil.shardIdForGuildId(guildId, shardCount);
} catch (err) {
  if (err.code === 'ShardingShardMiscalculation') {
    throw new Error(`Cannot map guild ${guildId} to shard: check shardCount (${shardCount}) and id validity`);
  }
  throw err;
}

When it happens

Trigger: Passing a negative or invalid shardCount; passing a guildId that cannot be parsed into the snowflake numeric range (e.g., empty string or corrupted value producing NaN/negative math); calling with a shardCount of 0 or a user-supplied count from bad config/env.

Common situations: Reading SHARD_COUNT from an env var that's unset or negative; passing a malformed guild id string from user input or a webhook payload; using shardIdForGuildId with a count that doesn't match the manager's actual shardCount.

Related errors

• ShardingProcessExists
• ShardingWorkerExists
• ShardingNoChildExists
• ClientInvalidOption
• CommandInteractionOptionInvalidChannelType

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