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 parts (`--shard i/N`) for horizontal distribution across CI machines. Watch mode keeps Vitest alive and re-runs tests reactively; combining the two is contradictory because sharding assumes one finite run. Vitest refuses to start rather than silently ignoring one of the flags.

Solutions

1. Drop `--watch` (or set `watch: false`) when sharding in CI.
2. Drop `--shard` when running interactively in watch mode.
3. Gate the flags on an `CI` env var so watch is only added locally.

Example fix

// before
vitest --watch --shard 1/4
// after (CI)
vitest --shard 1/4
// after (local)
vitest --watch

const watch = !process.env.CI && process.argv.includes('--watch')
const shard = process.env.SENTRY_SHARD
if (watch && shard) {
  throw new Error('Refusing to start: --watch and --shard are mutually exclusive.')
}

When it happens

Trigger: Running `vitest --watch --shard 1/2`, or setting both `watch: true` and `shard: '1/2'` in config/CLI, or a script that always passes `--watch` together with a CI shard env var.

Common situations: A dev script that hard-codes `--watch` reused in CI; an env var like `SHARD_INDEX` leaking into a local watch session.

Related errors

• Cannot merge reports with --watch enabled
• --shard must be a positive number less then
• --shard must be a positive number
• Vitest standalone mode requires --watch
• Blob reporter is not supported in watch mode

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/91e03115fe21154c. Report an issue: GitHub.

Appendix: source

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

  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 1fa9837ec2)