jestjs/jest · error · Error

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

Error message

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

What it means

parseShardPair's final structural check: the shard index (first number) must not exceed the shard count (second number). Running shard 5 of 3 is meaningless, so it is rejected. This catches ordering mistakes where the two numbers are swapped.

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 f49721c78e)

Solutions

1. Ensure the first number is <= the second number: --shard <index>/<total>
2. Verify the CI matrix total matches the number of parallel jobs
3. Double-check variable order if you renamed index/total

Example fix

// before (swapped)
jest --shard "$CI_NODE_TOTAL/$CI_NODE_INDEX"
// after
jest --shard "$CI_NODE_INDEX/$CI_NODE_TOTAL"

function validateShardRange(s: string): void {
  const [n, m] = s.split('/').map(Number);
  if (n > m) throw new Error(`shard index ${n} exceeds count ${m}`);
}

When it happens

Trigger: Passing `--shard "5/3"`, `--shard "4/2"`, or CI variables where index and total are accidentally interchanged.

Common situations: Swapping the index/total arguments in a CI matrix, or a matrix where the index variable runs higher than the declared total.

Related errors

• The shard option requires a string in the format of <n>/<m>.
• The shard option requires 1-based values, received 0 or lowe
• Can't find a root directory while resolving a config file pa
• Multiple configurations found Implicit config resolution d
• Could not find a config file based on provided values: path:

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/f3c8a4ceb6b15c08.json. Report an issue: GitHub.