jestjs/jest · error · Error

The shard option / requires to be lower or equal than .

Error message

The shard option <n>/<m> requires <n> to be lower or equal than <m>.

What it means

Thrown by parseShardPair when the shard index (n) exceeds the shard count (m). Since there are only m shards, requesting shard n>m references a shard that cannot exist. The pair is only valid when 1 <= n <= m.

Solutions

1. Ensure the shard index never exceeds the shard count
2. Audit the CI matrix so index and total originate from the same source
3. Add a preflight check: if [ "$INDEX" -gt "$TOTAL" ]; then exit 1; fi

Example fix

# before
jest --shard 5/3

# after
jest --shard 3/5

const [index, count] = shard.split('/').map(Number);
if (index > count) {
  throw new Error(`Shard index ${index} exceeds count ${count}`);
}

function isValidShardRange(pair: string): boolean {
  const [i, c] = pair.split('/').map(Number);
  return i >= 1 && c >= 1 && i <= c;
}

When it happens

Trigger: Passing --shard 5/3, --shard 4/2, or any pair where the first number is greater than the second. Common when the index and total are sourced from different systems that disagree.

Common situations: Mismatched CI matrix dimensions (e.g. index sourced from a 5-way job, total from a 3-way job), manual typos, or templating bugs where the two numbers come from different variables.

Related errors

• The shard option requires 1-based values, received 0 or…
• The shard option requires a string in the format of
• Shard / requested, but test sequencer in has no shard…
• Can't find a root directory while resolving a config file…
• Changed files must be set when running with -o.

AI-assisted analysis of jestjs/jest@8e6d128e4a (2026-08-10). Data as JSON: /api/errors/f3c8a4ceb6b15c08. Report an issue: GitHub.

Appendix: source

Thrown at packages/jest-config/src/parseShardPair.ts:33

    .filter(d => /^\d+$/.test(d))
    .map(d => Number.parseInt(d, 10));

  const [shardIndex, shardCount] = shardPair;

  if (shardPair.length !== 2) {
    throw new Error(
      'The shard option requires a string in the format of <n>/<m>.',
    );
  }

  if (shardIndex === 0 || shardCount === 0) {
    throw new Error(
      'The shard option requires 1-based values, received 0 or lower in the pair.',
    );
  }

  if (shardIndex > shardCount) {
    throw new Error(
      'The shard option <n>/<m> requires <n> to be lower or equal than <m>.',
    );
  }

  return {
    shardCount,
    shardIndex,
  };
};

View on GitHub (pinned to 8e6d128e4a)