jestjs/jest · error · Error

The shard option requires a string in the format of

Error message

The shard option requires a string in the format of <n>/<m>.

What it means

Thrown by parseShardPair when the --shard CLI argument cannot be split into exactly two integer parts separated by '/'. The function splits on '/', filters parts matching /^\d+$/, and requires exactly two surviving elements. Any value missing the slash, having non-numeric segments, or extra slashes produces this error.

Solutions

Provide the shard as two 1-based integers separated by '/', e.g. --shard 1/4
If templating in CI, ensure both variables are substituted, e.g. --shard "${CI_NODE_INDEX}/${CI_NODE_TOTAL}"
Validate the value is a string containing exactly one '/' with digits on both sides before invoking Jest

Example fix

// before
jest --shard 2

// after
jest --shard 2/4

Defensive patterns

Strategy: validation

Validate before calling

function isValidShardPair(pair: string): boolean {
  const parts = pair.split('/');
  if (parts.length !== 2) return false;
  return /^\d+$/.test(parts[0]) && /^\d+$/.test(parts[1]);
}

if (!isValidShardPair(process.env.SHARD)) {
  throw new Error(`Invalid shard pair: ${process.env.SHARD}`);
}

Type guard

function isShardPairString(value: unknown): value is string {
  if (typeof value !== 'string') return false;
  const parts = value.split('/');
  return parts.length === 2 && /^\d+$/.test(parts[0]) && /^\d+$/.test(parts[1]);
}

Prevention

Validate the shard string with a regex (/^\d+\/\d+$/) before passing it to Jest
In CI, assert both index and total variables are non-empty before composing the shard value
Centralize shard computation in one CI script so the format is correct in all jobs

When it happens

Trigger: Passing jest --shard without arguments, with a single integer like '2', with a reversed/garbled pair like '2-of-4', with a missing half like '/4', or with text like 'two/four' (filtered out by the digit regex). Also triggered by passing empty string.

Common situations: CI matrix scripts that template the shard value incorrectly (e.g. $INDEX without $COUNT), shell quoting bugs that drop the slash, or copy-pasting shard syntax from older docs that used a different separator.

Related errors

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

Appendix: source

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

 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */
export interface ShardPair {
  shardCount: number;
  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,

View on GitHub (pinned to 8e6d128e4a)