jestjs/jest · error · Error

The shard option requires 1-based values, received 0 or lowe

Error message

The shard option requires 1-based values, received 0 or lower in the pair.

What it means

After parseShardPair confirms two numeric segments exist, it checks that neither is zero. Shards are 1-based, so both shard index 0 and shard count 0 are invalid. The /^\d+$/ pre-filter already excludes negatives, but "0" is a digit so it reaches this explicit guard.

Source

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

  shardIndex: number;
}

export const parseShardPair = (pair: string): ShardPair => {
  const shardPair = pair
    .split('/')
    .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

Use 1-based values: the first shard is --shard 1/N and the last is --shard N/N
If your CI is 0-based, add 1 to the index before passing it: --shard "$((CI_NODE_INDEX+1))/$CI_NODE_TOTAL"
Ensure the shard count (second number) is at least 1

Example fix

// before (0-based CI index)
jest --shard "$CI_NODE_INDEX/$CI_NODE_TOTAL"
// after
jest --shard "$((CI_NODE_INDEX + 1))/$CI_NODE_TOTAL"

Defensive patterns

Strategy: validation

Validate before calling

function validateShardValues(s: string): void {
  const [n, m] = s.split('/').map(Number);
  if (!n || n < 1 || !m || m < 1) {
    throw new Error('shard values must be >= 1');
  }
}

Prevention

Document in CI config comments that Jest shards are 1-based
Assert shard index >= 1 in CI before invoking jest

When it happens

Trigger: Passing `--shard "0/4"` (zero index), `--shard "2/0"` (zero count), `--shard "0/0"`, or a CI variable that defaults to 0.

Common situations: CI platforms that use 0-based indexing (some Docker/parallel setups) being fed into Jest's 1-based shard option; off-by-one in matrix arithmetic.

Related errors

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