vitest-dev/vitest · error · Error

Cannot merge reports with --watch enabled

Error message

Cannot merge reports with --watch enabled

What it means

`--merge-reports` combines coverage/result blobs written by previous sharded runs into a single report. Watch mode keeps re-running tests, so merging mid-watch would race against ongoing writes. The guard at resolveConfig.ts:348 forbids combining them.

Source

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

    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 }
  }

  if (resolved.standalone && !resolved.watch) {
    throw new Error(`Vitest standalone mode requires --watch`)
  }

  if (resolved.mergeReports && resolved.watch) {
    throw new Error(`Cannot merge reports with --watch enabled`)
  }

  if (resolved.maxWorkers) {
    resolved.maxWorkers = resolveInlineWorkerOption(resolved.maxWorkers)
  }

  // `browser.fileParallelism` was replaced by the top-level `fileParallelism`. Map
  // it (only when browser is enabled, since it was a browser-only option) so
  // existing configs keep working instead of being silently ignored.
  const browserOptions = options.browser as { enabled?: boolean; fileParallelism?: boolean } | undefined
  const browserFileParallelism = browserOptions?.enabled ? browserOptions.fileParallelism : undefined
  if (browserFileParallelism !== undefined) {
    logger.deprecate('`browser.fileParallelism` is deprecated. Use the top-level `fileParallelism` option instead.')
  }

  const fileParallelism = options.fileParallelism ?? browserFileParallelism ?? true

  if (!fileParallelism) {

View on GitHub (pinned to d568f8ce37)

Solutions

1. Drop --watch for the merge step: `vitest --merge-reports --no-watch`.
2. Use a dedicated CI config without watch for both the sharded runs and the merge.
3. Confirm watch is off (CI auto-disables it, but explicit config can re-enable it).

Example fix

# before
vitest --merge-reports --watch
# after
vitest --merge-reports

function assertMergeReportsNotWatch(opts: { mergeReports?: boolean; watch?: boolean }) {
  if (opts.mergeReports && opts.watch) throw new Error('Cannot merge reports while watch is enabled')
}

When it happens

Trigger: Run `vitest --merge-reports --watch` or have `watch: true` in config while invoking the merge step.

Common situations: Reusing a dev config (watch on) for the post-CI report-merge step; leaving --watch in a script that wraps merge-reports.

Related errors

• You cannot use --shard option with enabled watch
• --shard <count> must be a positive number
• --shard <index> must be a positive number less then <count>
• Vitest standalone mode requires --watch
• vitest.mergeReports() requires all blob files to be generate

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