{"record":{"id":"afe702a3be5f5b96","repo":"jestjs/jest","slug":"the-shard-option-requires-1-based-values-received","errorCode":null,"errorMessage":"The shard option requires 1-based values, received 0 or lower in the pair.","messagePattern":"The shard option requires 1-based values, received 0 or lower in the pair\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/jest-config/src/parseShardPair.ts","lineNumber":27,"sourceCode":"  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,\n    shardIndex,\n  };\n};\n","sourceCodeStart":9,"sourceCodeEnd":43,"githubUrl":"https://github.com/jestjs/jest/blob/8e6d128e4a278059ecddecaa97400b04c8ae5fd9/packages/jest-config/src/parseShardPair.ts#L9-L43","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Convert 0-based CI indices to 1-based before passing to Jest: --shard \"$((CI_NODE_INDEX + 1))/$CI_NODE_TOTAL\"","Verify the shard count is at least 1","Add a guard in your CI script that fails fast when either value is 0"],"exampleFix":"// before (GitLab 0-based)\njest --shard \"$CI_NODE_INDEX/$CI_NODE_TOTAL\"\n\n// after\njest --shard \"$((CI_NODE_INDEX + 1))/$CI_NODE_TOTAL\"","handlingStrategy":"validation","validationCode":"function assertShardPair(pair: string): void {\n  const [index, count] = pair.split('/').map(Number);\n  if (!Number.isInteger(index) || !Number.isInteger(count)) {\n    throw new Error('Shard pair must be two integers');\n  }\n  if (index < 1 || count < 1) {\n    throw new Error('Shard pair must be 1-based and >= 1');\n  }\n}","typeGuard":"function isOneBasedShardPair(pair: string): boolean {\n  const parts = pair.split('/');\n  if (parts.length !== 2) return false;\n  const [i, c] = parts.map(Number);\n  return i >= 1 && c >= 1;\n}","tryCatchPattern":null,"preventionTips":["Always add 1 to zero-based CI indices before composing the shard value","Document the 1-based convention in your CI matrix template","Fail the CI job early if either number is 0"],"tags":["cli","sharding","ci","off-by-one","argument-validation"],"backgroundTag":null,"analyzedSha":"8e6d128e4a278059ecddecaa97400b04c8ae5fd9","analyzedAt":"2026-08-10T18:11:27.960Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}