jestjs/jest · error · Error

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

Error message

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

What it means

parseShardPair parses the `--shard <n>/<m>` CLI argument used to split a test suite into parallel shards. The input is split on `/`, each segment must match /^\d+$/, and exactly two numeric segments must remain after filtering. If zero, one, or three+ numeric parts survive, this error is thrown, guarding the shard-string contract before any test discovery runs.

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

Solutions

1. Format the shard argument as exactly two positive integers separated by a single slash, e.g. --shard 1/4
2. Check that any shell/CI variables embedded in the shard string are set and non-empty before jest runs
3. If calling parseShardPair programmatically, validate the string matches /^\d+\/\d+$/ before calling

Example fix

// before
jest --shard $CI_NODE_INDEX  # missing total
// after
jest --shard "$CI_NODE_INDEX/$CI_NODE_TOTAL"

const SHARD_RE = /^(\d+)\/(\d+)$/;
function isValidShardPair(s: string): boolean {
  return SHARD_RE.test(s);
}
// before invoking jest or parseShardPair:
if (!isValidShardPair(process.env.SHARD ?? '')) {
  throw new Error(`Invalid shard string: ${process.env.SHARD}`);
}

function isShardPair(s: string): s is `${number}/${number}` {
  return /^\d+\/\d+$/.test(s);
}

When it happens

Trigger: Calling jest with `--shard "2"` (no slash), `--shard "2/3/4"` (extra segment), `--shard "abc/def"` (both filtered out -> zero), `--shard "x/2"` (one filtered out), or programmatically calling parseShardPair("a/b").

Common situations: Shell variable expansion producing empty values in CI (e.g. `--shard "/$CI_NODE_TOTAL"`), copy-paste errors in GitHub Actions / GitLab CI shard matrix, or passing an integer where a string is expected.

Related errors

• The shard option requires 1-based values, received 0 or lowe
• The shard option <n>/<m> requires <n> to be lower or equal t
• 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/c1b20d4f18f579ee.json. Report an issue: GitHub.