{"id":"c1b20d4f18f579ee","repo":"jestjs/jest","slug":"the-shard-option-requires-a-string-in-the-format-o","errorCode":null,"errorMessage":"The shard option requires a string in the format of <n>/<m>.","messagePattern":"The shard option requires a string in the format of <n>/<m>\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/jest-config/src/parseShardPair.ts","lineNumber":21,"sourceCode":" *\n * This source code is licensed under the MIT license found in the\n * LICENSE file in the root directory of this source tree.\n */\nexport interface ShardPair {\n  shardCount: number;\n  shardIndex: number;\n}\n\nexport const parseShardPair = (pair: string): ShardPair => {\n  const shardPair = pair\n    .split('/')\n    .filter(d => /^\\d+$/.test(d))\n    .map(d => Number.parseInt(d, 10));\n\n  const [shardIndex, shardCount] = shardPair;\n\n  if (shardPair.length !== 2) {\n    throw new Error(\n      'The shard option requires a string in the format of <n>/<m>.',\n    );\n  }\n\n  if (shardIndex === 0 || shardCount === 0) {\n    throw new Error(\n      'The shard option requires 1-based values, received 0 or lower in the pair.',\n    );\n  }\n\n  if (shardIndex > shardCount) {\n    throw new Error(\n      'The shard option <n>/<m> requires <n> to be lower or equal than <m>.',\n    );\n  }\n\n  return {\n    shardCount,","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/jest-config/src/parseShardPair.ts#L3-L39","documentation":"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.","triggerScenarios":"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\").","commonSituations":"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.","solutions":["Format the shard argument as exactly two positive integers separated by a single slash, e.g. --shard 1/4","Check that any shell/CI variables embedded in the shard string are set and non-empty before jest runs","If calling parseShardPair programmatically, validate the string matches /^\\d+\\/\\d+$/ before calling"],"exampleFix":"// before\njest --shard $CI_NODE_INDEX  # missing total\n// after\njest --shard \"$CI_NODE_INDEX/$CI_NODE_TOTAL\"","handlingStrategy":"validation","validationCode":"const SHARD_RE = /^(\\d+)\\/(\\d+)$/;\nfunction isValidShardPair(s: string): boolean {\n  return SHARD_RE.test(s);\n}\n// before invoking jest or parseShardPair:\nif (!isValidShardPair(process.env.SHARD ?? '')) {\n  throw new Error(`Invalid shard string: ${process.env.SHARD}`);\n}","typeGuard":"function isShardPair(s: string): s is `${number}/${number}` {\n  return /^\\d+\\/\\d+$/.test(s);\n}","tryCatchPattern":null,"preventionTips":["Always quote CI variables in --shard arguments to avoid empty-segment expansion","Derive shard index and total from a single CI matrix source","Unit-test the shard string in a pre-check job before the test job runs"],"tags":["cli","sharding","ci"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}