vitest-dev/vitest · error

You cannot use without "--no-file-parallelism

Error message

You cannot use ${inspectOption} without "--no-file-parallelism"

What it means

The Node inspector (`--inspect` / `--inspect-brk`) attaches to a single process to allow stepping through test code. With file parallelism, tests run across multiple workers/processes and the inspector cannot meaningfully attach. Vitest requires `maxWorkers === 1` (i.e. `--no-file-parallelism` or `--maxWorkers 1`) when inspecting.

Solutions

1. Add `--no-file-parallelism` (or `--maxWorkers 1`) alongside `--inspect`/`--inspect-brk`.
2. Set `fileParallelism: false` in the debug-only config preset.
3. Use a dedicated `test:debug` script that bundles both flags.

Example fix

# before
vitest --inspect-brk
# after
vitest --inspect-brk --no-file-parallelism

const inspect = process.argv.some(a => a.startsWith('--inspect'))
if (inspect && !process.argv.includes('--no-file-parallelism')) {
  console.warn('Auto-adding --no-file-parallelism because --inspect was passed.')
  process.argv.push('--no-file-parallelism')
}

When it happens

Trigger: Running `vitest --inspect-brk` while `fileParallelism` is true or `maxWorkers` is unset (defaults to >1), or setting both `inspectBrk: true` and a multi-worker pool.

Common situations: Forgetting to disable parallelism when debugging; a CI config that always pins workers clashing with a local debug flag.

Related errors

• Inspector host cannot be a URL. Use "host:port" instead of
• "browser.instances" was set in the config, but the array is…
• --cache.dir is deprecated
• Cannot merge reports with --watch enabled
• Expected a single value for option

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

Appendix: source

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

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

  if (!fileParallelism) {
    // ignore user config, parallelism cannot be implemented without limiting workers
    resolved.maxWorkers = 1
  }

  if (resolved.maxConcurrency === 0) {
    logger.console.warn(
      c.yellow(`The option "maxConcurrency" cannot be set to 0. Using default value ${configDefaults.maxConcurrency} instead.`),
    )
    resolved.maxConcurrency = configDefaults.maxConcurrency
  }

  if (resolved.inspect || resolved.inspectBrk) {
    if (resolved.maxWorkers !== 1) {
      const inspectOption = `--inspect${resolved.inspectBrk ? '-brk' : ''}`
      throw new Error(
        `You cannot use ${inspectOption} without "--no-file-parallelism"`,
      )
    }
  }

  resolved.browser ??= {} as any
  const browser = resolved.browser

  if (browser.enabled) {
    const instances = browser.instances
    if (!browser.instances) {
      browser.instances = []
    }

    // The whole project shares a single browser Vite server, so every instance
    // must use the same provider. Validate that here and hoist the provider to
    // the project level so the cluster resolves one even when it is only set per
    // instance (e.g. connect mode). Because the provider is uniform, any

View on GitHub (pinned to 1fa9837ec2)