vitest-dev/vitest · error · Error

does not work with Use either: ...or disable

Error message

${inspectOption} does not work with
${browserConfig}

Use either:
${correctExample}

...or disable ${inspectOption}

What it means

`--inspect`/`--inspect-brk` start Node's V8 inspector on the main/server process. In browser mode with the `preview` provider or a non-Chromium browser, the actual test code runs inside the browser, so the Node inspector cannot reach it and the debug session would be a silent no-op. Vitest refuses to start and points you at either a Chromium-based browser config (which supports CDP debugging) or disabling the flag.

Solutions

Drop `--inspect`/`--inspect-brk` from the Vitest invocation when running browser tests.
Or switch the browser instance to a Chromium-based provider/browser (`playwright`+`chromium`, or `webdriverio`+`chrome`/`edge`) so CDP debugging applies.
Split Node and browser projects so the inspect flag only applies to the Node project.

Example fix

// before: vitest --inspect --project=browser-firefox
// browser: { provider: 'playwright', instances: [{ browser: 'firefox' }] }

// after: run the browser project without inspect
//   vitest --project=browser-firefox
// and only inspect Node projects:
//   vitest --inspect --project=node-core

Defensive patterns

Strategy: validation

Validate before calling

// Don't pass --inspect to a browser project that can't use it.
function assertInspectBrowserCompatible(globalConfig: { inspect?: boolean; inspectBrk?: boolean }, test: { browser?: any }) {
  const inspecting = globalConfig.inspect || globalConfig.inspectBrk
  if (!inspecting) return
  const instances = test.browser?.instances ?? []
  for (const i of instances) {
    const provider = i.provider?.name ?? test.browser?.provider?.name ?? 'preview'
    const chromium =
      provider === 'playwright' ? i.browser === 'chromium'
      : provider === 'webdriverio' ? (i.browser === 'chrome' || i.browser === 'edge')
      : false
    if (provider === 'preview' || !chromium) {
      throw new Error(`--inspect is incompatible with non-Chromium browser instance '${i.browser}'. Drop the flag or switch to chromium.`)
    }
  }
}

Prevention

Scope `--inspect` to Node-only projects via `--project` selection.
Keep browser projects on Chromium targets when you need to debug them (use CDP/DevTools instead of `--inspect`).

When it happens

Trigger: `globalConfig.inspect === true` OR `globalConfig.inspectBrk === true`, while resolving a browser instance that falls into the CDP-only branch (`provider === 'preview'` or `!isChromiumName(provider, browser)`). `inspectOption` is rendered as `--inspect` or `--inspect-brk`.

Common situations: Running `vitest --inspect` while a browser project is configured with the preview provider or playwright firefox/webkit; defaulting `inspectBrk` in a launch config shared with browser projects.

Related errors

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

Appendix: source

Thrown at packages/vitest/src/node/projects/resolveProjects.ts:937

          const coverageExample = `
{
  coverage: {
    provider: 'istanbul',
  },
}
            `.trim()

          throw new Error(
            `@vitest/coverage-v8 does not work with\n${browserConfig}\n`
            + `\nUse either:\n${correctExample}`
            + `\n\n...or change your coverage provider to:\n${coverageExample}\n`,
          )
        }

        if (globalConfig.inspect || globalConfig.inspectBrk) {
          const inspectOption = `--inspect${globalConfig.inspectBrk ? '-brk' : ''}`

          throw new Error(
            `${inspectOption} does not work with\n${browserConfig}\n`
            + `\nUse either:\n${correctExample}`
            + `\n\n...or disable ${inspectOption}\n`,
          )
        }
      }

      if (names.has(name)) {
        throw new Error(
          [
            `Cannot define a nested project for a ${browser} browser. The project name "${name}" was already defined. `,
            'If you have multiple instances for the same browser, make sure to define a custom "name". ',
            'All projects should have unique names. Make sure your configuration is correct.',
          ].join(''),
        )
      }
      names.add(name)

View on GitHub (pinned to 1fa9837ec2)