{"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":336,"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":318,"sourceCodeEnd":354,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/node/config/resolveConfig.ts#L318-L354","documentation":"The shard index must be in the range [1, count]. This fires when the index is missing, non-numeric, <= 0, or greater than count. Without a valid index Vitest cannot select which slice of files to run.","triggerScenarios":"Run `vitest --shard 5/4` (index exceeds count), `vitest --shard 0/4` (zero-based mistake), or `vitest --shard abc/4`.","commonSituations":"CI matrix using 1-based index but the runner variable is 0-based; off-by-one when generating the matrix; typo'd index.","solutions":["Use a 1-based index no larger than count: `--shard 1/4` through `--shard 4/4`.","If your CI gives a 0-based shard index, add 1: `--shard $((SHARD_INDEX + 1))/${SHARD_TOTAL}`.","Double-check the matrix size matches the count you pass."],"exampleFix":"# before (CI matrix index 0..3)\nvitest --shard ${INDEX}/4\n# after\nvitest --shard $((INDEX + 1))/4","handlingStrategy":"validation","validationCode":"function assertShardIndex(raw: string) {\n  const [i, c] = raw.split('/').map(Number)\n  if (!(i >= 1 && i <= c)) throw new Error(`Shard index must be in [1, ${c}], got ${i}`)\n}","typeGuard":"function isShardIndexInRange(raw: string): boolean {\n  const [i, c] = raw.split('/').map(Number)\n  return i >= 1 && i <= c\n}","tryCatchPattern":null,"preventionTips":["Convert 0-based CI matrix indices to 1-based before passing to vitest.","Assert index <= count in your CI script.","Document the 1-based convention in the repo's CI readme."],"tags":["cli","shard","validation","ci"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}