vitest-dev/vitest · error · Error

You cannot use --shard option with enabled watch

Error message

You cannot use --shard option with enabled watch

What it means

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.

Source

Thrown at packages/vitest/src/node/config/resolveConfig.ts:324

  const inspector = resolved.inspect || resolved.inspectBrk

  resolved.inspector = {
    ...resolved.inspector,
    ...parseInspector(inspector),
    enabled: !!inspector,
    waitForDebugger:
      options.inspector?.waitForDebugger ?? !!resolved.inspectBrk,
  }

  if (viteConfig.base !== '/') {
    resolved.base = viteConfig.base
  }

  resolved.clearScreen = resolved.clearScreen ?? viteConfig.clearScreen ?? true

  if (options.shard) {
    if (resolved.watch) {
      throw new Error('You cannot use --shard option with enabled watch')
    }

    const [indexString, countString] = options.shard.split('/')
    const index = Math.abs(Number.parseInt(indexString, 10))
    const count = Math.abs(Number.parseInt(countString, 10))

    if (Number.isNaN(count) || count <= 0) {
      throw new Error('--shard <count> must be a positive number')
    }

    if (Number.isNaN(index) || index <= 0 || index > count) {
      throw new Error(
        '--shard <index> must be a positive number less then <count>',
      )
    }

    resolved.shard = { index, count }
  }

View on GitHub (pinned to d568f8ce37)

Solutions

1. Drop --shard when running in watch mode; sharding is a CI/one-shot concept.
2. If sharding in CI, ensure watch is off: `vitest --shard 1/4 --no-watch` (watch defaults to off in CI).
3. Separate your dev and CI configs so watch is not inherited by the sharded run.

Example fix

# before
vitest --shard 1/4 --watch
# after
vitest --shard 1/4

function assertShardWatchCompatible(opts: { shard?: string; watch?: boolean }) {
  if (opts.shard && opts.watch) {
    throw new Error('Cannot use --shard with watch enabled. Disable watch for sharded CI runs.')
  }
}

When it happens

Trigger: Run `vitest --shard 1/4 --watch` or set `watch: true` in config while passing `--shard` on the CLI.

Common situations: Leaving `watch: true` in a dev config and reusing it in CI with --shard; passing --shard through a script that also sets --watch.

Related errors

• --shard <count> must be a positive number
• --shard <index> must be a positive number less then <count>
• Cannot merge reports with --watch enabled
• Vitest standalone mode requires --watch
• You cannot use ${inspectOption} without "--no-file-paralleli

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/91e03115fe21154c.json. Report an issue: GitHub.