{"id":"64c2f3383b41ba14","repo":"vitest-dev/vitest","slug":"shard-count-must-be-a-positive-number","errorCode":null,"errorMessage":"--shard <count> must be a positive number","messagePattern":"--shard <count> must be a positive number","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/node/config/resolveConfig.ts","lineNumber":332,"sourceCode":"  }\n\n  if (viteConfig.base !== '/') {\n    resolved.base = viteConfig.base\n  }\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  }","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/node/config/resolveConfig.ts#L314-L350","documentation":"The --shard flag takes the form `<index>/<count>`. This error fires when the count portion is missing, non-numeric, or zero. The check at resolveConfig.ts:331 parses the count via Number.parseInt and rejects NaN or values <= 0, because a shard count of 0 makes the index meaningless.","triggerScenarios":"Run `vitest --shard 1/0`, `vitest --shard 2/abc`, or `vitest --shard 3` (missing the slash and count).","commonSituations":"Typo in a CI matrix script; dynamic shard count from a variable that evaluated to empty/0; misreading the shard format as a single number.","solutions":["Pass both index and count as positive integers: `--shard 1/4`.","If the count comes from a CI variable, verify it is set and numeric before invoking vitest.","Quote the value in shell to avoid glob/word-splitting: `--shard \"${INDEX}/${TOTAL}\"`."],"exampleFix":"# before\nvitest --shard 1/0\n# after\nvitest --shard 1/4","handlingStrategy":"validation","validationCode":"function parseShard(raw: string): { index: number; count: number } {\n  const [i, c] = raw.split('/')\n  const count = Number.parseInt(c, 10)\n  if (Number.isNaN(count) || count <= 0) throw new Error(`Invalid shard count: ${raw}`)\n  const index = Number.parseInt(i, 10)\n  if (Number.isNaN(index) || index <= 0 || index > count) throw new Error(`Invalid shard index: ${raw}`)\n  return { index, count }\n}","typeGuard":"function isValidShard(raw: string): boolean {\n  const [i, c] = raw.split('/')\n  const count = Number.parseInt(c, 10)\n  const index = Number.parseInt(i, 10)\n  return !Number.isNaN(count) && count > 0 && !Number.isNaN(index) && index > 0 && index <= count\n}","tryCatchPattern":null,"preventionTips":["Always quote `--shard \"${INDEX}/${COUNT}\"` in CI scripts.","Validate shard variables are set and numeric before invoking vitest.","Use a 1-based matrix index."],"tags":["cli","shard","validation","ci"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}