jestjs/jest · error · Error

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

Error message

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

What it means

Thrown by parseShardPair when either the shard index or shard count resolves to zero. The sharding scheme is 1-based, so '0/4' and '1/0' are both invalid. A zero count would mean no shards exist, and a zero index has no shard to assign tests to.

Solutions

1. Convert 0-based CI indices to 1-based before passing to Jest: --shard "$((CI_NODE_INDEX + 1))/$CI_NODE_TOTAL"
2. Verify the shard count is at least 1
3. Add a guard in your CI script that fails fast when either value is 0

Example fix

// before (GitLab 0-based)
jest --shard "$CI_NODE_INDEX/$CI_NODE_TOTAL"

// after
jest --shard "$((CI_NODE_INDEX + 1))/$CI_NODE_TOTAL"

function assertShardPair(pair: string): void {
  const [index, count] = pair.split('/').map(Number);
  if (!Number.isInteger(index) || !Number.isInteger(count)) {
    throw new Error('Shard pair must be two integers');
  }
  if (index < 1 || count < 1) {
    throw new Error('Shard pair must be 1-based and >= 1');
  }
}

function isOneBasedShardPair(pair: string): boolean {
  const parts = pair.split('/');
  if (parts.length !== 2) return false;
  const [i, c] = parts.map(Number);
  return i >= 1 && c >= 1;
}

When it happens

Trigger: Passing --shard 0/4 (off-by-one from zero-based CI indexing), --shard 1/0 (templated total that resolved to empty/zero), or any pair where one side is '0'.

Common situations: CI platforms (GitLab, Buildkite) that use 0-based node indexing where developers forget to add 1; scripts that compute total shards from a count that is zero before matrix population; misconfigured parallelism.

Related errors

• The shard option / requires to be lower or equal than .
• 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/afe702a3be5f5b96. Report an issue: GitHub.

Appendix: 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 8e6d128e4a)