{"record":{"id":"1326fc0225083f34","repo":"vitest-dev/vitest","slug":"shard-index-must-be-a-positive-number-less-the","errorCode":null,"errorMessage":"--shard <index> must be a positive number less then <count>","messagePattern":"--shard <index> must be a positive number less then <count>","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/node/config/resolveConfig.ts","lineNumber":364,"sourceCode":"  }\n\n  resolved.clearScreen = resolved.clearScreen ?? viteConfig.clearScreen ?? true\n\n  if (options.shard) {\n    if (resolved.watch) {\n      throw new Error('You cannot use --shard option with enabled watch')\n    }\n\n    const [indexString, countString] = options.shard.split('/')\n    const index = Math.abs(Number.parseInt(indexString, 10))\n    const count = Math.abs(Number.parseInt(countString, 10))\n\n    if (Number.isNaN(count) || count <= 0) {\n      throw new Error('--shard <count> must be a positive number')\n    }\n\n    if (Number.isNaN(index) || index <= 0 || index > count) {\n      throw new Error(\n        '--shard <index> must be a positive number less then <count>',\n      )\n    }\n\n    resolved.shard = { index, count }\n  }\n\n  if (resolved.standalone && !resolved.watch) {\n    throw new Error(`Vitest standalone mode requires --watch`)\n  }\n\n  if (resolved.mergeReports && resolved.watch) {\n    throw new Error(`Cannot merge reports with --watch enabled`)\n  }\n\n  if (resolved.maxWorkers) {\n    resolved.maxWorkers = resolveInlineWorkerOption(resolved.maxWorkers)\n  }","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/vitest/src/node/config/resolveConfig.ts#L346-L382","documentation":"After the count is validated, Vitest checks the shard index (numerator). The index must be a positive integer that does not exceed count. This fires on NaN, 0, negative, or an index greater than the total number of shards.","triggerScenarios":"`--shard 0/4`, `--shard 5/4` (index > count), `--shard abc/4`, or a CI 1-based vs 0-based indexing mismatch producing index 0.","commonSituations":"CI provider uses 0-based shard indices while Vitest expects 1-based; a matrix where `i` runs from 1..N but the off-by-one sends N+1.","solutions":["Use a 1-based index between 1 and count inclusive.","If your CI gives 0-based indices, add 1 before passing to `--shard`.","Double-check the matrix size equals the shard count."],"exampleFix":"# before (0-based CI)\nvitest --shard 0/4\n# after\nvitest --shard 1/4","handlingStrategy":"validation","validationCode":"const nodeIndex = Number(process.env.CI_NODE_INDEX ?? '1') // 0-based from some CIs\nconst nodeTotal = Number(process.env.CI_NODE_TOTAL ?? '1')\nconst shardIndex = nodeIndex + 1 // convert to 1-based for vitest\nif (shardIndex < 1 || shardIndex > nodeTotal) {\n  throw new Error(`Computed shard ${shardIndex}/${nodeTotal} is out of range`)\n}\nprocess.argv.push('--shard', `${shardIndex}/${nodeTotal}`)","typeGuard":"function isValidShardString(raw: string): boolean {\n  const m = /^(\\d+)\\/(\\d+)$/.exec(raw)\n  if (!m) return false\n  return Number(m[1]) >= 1 && Number(m[1]) <= Number(m[2])\n}","tryCatchPattern":null,"preventionTips":["Document which CI env vars are 0-based and normalise to 1-based in a helper.","Use a matrix where `i` runs 1..N inclusive."],"tags":["cli","shard","validation","ci"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}