vitest-dev/vitest · error · Error

Vitest standalone mode requires --watch

Error message

Vitest standalone mode requires --watch

What it means

Standalone mode (`--standalone`) starts Vitest without an initial test run and keeps the Vite server warm so subsequent invocations reuse it. It only makes sense paired with `--watch`, otherwise the server would start and immediately exit. Vitest rejects the combination of standalone + no-watch up front.

Solutions

1. Add `--watch` (or set `watch: true`) when using `--standalone`.
2. Drop `--standalone` if you want a one-shot run.
3. Check that a `watch: false` default in config is not overriding the CLI flag.

Example fix

# before
vitest --standalone
# after
vitest --standalone --watch

const standalone = process.argv.includes('--standalone')
const watch = process.argv.includes('--watch')
if (standalone && !watch) {
  throw new Error('--standalone requires --watch; add it or drop --standalone.')
}

When it happens

Trigger: Running `vitest --standalone` without `--watch`, or setting `standalone: true` while `watch: false` in config.

Common situations: Wrapping `--standalone` in a dev script that separately sets `watch: false`; a config default that forces `watch: false`.

Related errors

• Cannot merge reports with --watch enabled
• You cannot use --shard option with enabled watch
• Blob reporter is not supported in watch mode
• "browser.instances" was set in the config, but the array is…
• --cache.dir is deprecated

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

Appendix: source

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

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

  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.')
  }

View on GitHub (pinned to 1fa9837ec2)