{"id":"91e03115fe21154c","repo":"vitest-dev/vitest","slug":"you-cannot-use-shard-option-with-enabled-watch","errorCode":null,"errorMessage":"You cannot use --shard option with enabled watch","messagePattern":"You cannot use --shard option with enabled watch","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/node/config/resolveConfig.ts","lineNumber":324,"sourceCode":"  const inspector = resolved.inspect || resolved.inspectBrk\n\n  resolved.inspector = {\n    ...resolved.inspector,\n    ...parseInspector(inspector),\n    enabled: !!inspector,\n    waitForDebugger:\n      options.inspector?.waitForDebugger ?? !!resolved.inspectBrk,\n  }\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  }","sourceCodeStart":306,"sourceCodeEnd":342,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/node/config/resolveConfig.ts#L306-L342","documentation":"Sharding splits a single test run into N disjoint parts for horizontal scaling across CI machines; watch mode re-runs the whole suite on every file change. The two are incompatible because a shard cannot meaningfully watch a subset that shifts as files change. The guard at resolveConfig.ts:323 rejects the combination outright.","triggerScenarios":"Run `vitest --shard 1/4 --watch` or set `watch: true` in config while passing `--shard` on the CLI.","commonSituations":"Leaving `watch: true` in a dev config and reusing it in CI with --shard; passing --shard through a script that also sets --watch.","solutions":["Drop --shard when running in watch mode; sharding is a CI/one-shot concept.","If sharding in CI, ensure watch is off: `vitest --shard 1/4 --no-watch` (watch defaults to off in CI).","Separate your dev and CI configs so watch is not inherited by the sharded run."],"exampleFix":"# before\nvitest --shard 1/4 --watch\n# after\nvitest --shard 1/4","handlingStrategy":"validation","validationCode":"function assertShardWatchCompatible(opts: { shard?: string; watch?: boolean }) {\n  if (opts.shard && opts.watch) {\n    throw new Error('Cannot use --shard with watch enabled. Disable watch for sharded CI runs.')\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep watch out of CI configs that also shard.","Run sharded jobs with --no-watch explicitly.","Separate dev and CI config files."],"tags":["cli","shard","watch","ci"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}