vitest-dev/vitest · error · Error

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

Error message

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

What it means

Node's inspector attaches to a single process; Vitest's file parallelism runs multiple worker threads/processes, so the debugger would either attach to the wrong one or none. The check at resolveConfig.ts:380 requires maxWorkers === 1 (i.e. --no-file-parallelism) when --inspect or --inspect-brk is used, ensuring the inspector hits the only worker running your tests.

Source

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

  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 d568f8ce37)

Solutions

1. Add --no-file-parallelism: `vitest --inspect --no-file-parallelism`.
2. Or set `fileParallelism: false` in config when debugging.
3. For --inspect-brk, also pair with --no-file-parallelism so the breakpoint halts the single worker.

Example fix

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

function assertInspectNeedsSingleWorker(opts: { inspect?: boolean; inspectBrk?: boolean; fileParallelism?: boolean }) {
  if ((opts.inspect || opts.inspectBrk) && opts.fileParallelism !== false) {
    throw new Error('Pass --no-file-parallelism when using --inspect/--inspect-brk')
  }
}

When it happens

Trigger: Run `vitest --inspect` without also passing `--no-file-parallelism`, or set `inspect: true` in config while fileParallelism stays default (true).

Common situations: Trying to debug a test with the inspector for the first time; forgetting that parallelism is on by default.

Related errors

• ${inspectOption} does not work with ${browserConfig} Use ei
• Tag "${tag.name}": retry.condition function cannot be used i
• 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>

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