vitest-dev/vitest · error · Error

All browser instances within a project must use the same pro

Error message

All browser instances within a project must use the same provider, but found: ${[...providerNames].join(', ')}. Use a single provider for the project, or move the instances into separate projects.

What it means

A Vitest project shares one browser Vite server, so every browser instance in that project must resolve to the same provider (both by name and by factory reference). The check at resolveConfig.ts:415 collects provider names and factory references from the project-level `browser.provider` and each `browser.instances[].provider`, and throws if more than one distinct provider is found.

Source

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

    // 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
    // instance's server factory represents the whole project.
    const providerNames = new Set<string>()
    // It's possible to provide the same name and sneak in a different factory
    const providerFactories = new Set()
    if (browser.provider?.name) {
      providerNames.add(browser.provider.name)
      providerFactories.add(browser.provider.serverFactory)
    }
    for (const instance of browser.instances) {
      if (instance.provider?.name) {
        providerNames.add(instance.provider.name)
        providerFactories.add(instance.provider.serverFactory)
      }
    }
    if (providerNames.size > 1 || providerFactories.size > 1) {
      throw new Error(
        `All browser instances within a project must use the same provider, but found: ${[...providerNames].join(', ')}. `
        + `Use a single provider for the project, or move the instances into separate projects.`,
      )
    }
    browser.provider ??= browser.instances.find(instance => instance.provider)?.provider

    // use `chromium` by default when the preview provider is specified
    // for a smoother experience. if chromium is not available, it will
    // open the default browser anyway
    if (!browser.instances.length && browser.provider?.name === 'preview') {
      browser.instances = [{ browser: 'chromium' }]
    }

    if (browser.name && instances?.length) {
      // --browser=chromium filters configs to a single one
      browser.instances = browser.instances.filter(instance => instance.browser === browser.name)

      // if `instances` were defined, but now they are empty,

View on GitHub (pinned to d568f8ce37)

Solutions

Use a single provider for all instances in the project (set it once at `browser.provider` and omit per-instance providers).
Move instances that need a different provider into a separate Vitest project (separate `defineProject`/workspace entry).
Remove the per-instance `provider` overrides so they inherit the project-level factory.

Example fix

// before
export default defineProject({ test: { browser: { enabled: true, instances: [
  { browser: 'chromium', provider: playwright },
  { browser: 'webkit', provider: webdriverio },
] } } })
// after — split into two projects
export default defineWorkspace([
  { test: { name: 'pw', browser: { enabled: true, provider: playwright, instances: [{ browser: 'chromium' }] } } },
  { test: { name: 'wdio', browser: { enabled: true, provider: webdriverio, instances: [{ browser: 'webkit' }] } } },
])

Defensive patterns

Strategy: type-guard

Validate before calling

function assertSingleBrowserProvider(project: { browser?: { provider?: any; instances?: { provider?: any }[] } }) {
  const names = new Set<string>()
  if (project.browser?.provider?.name) names.add(project.browser.provider.name)
  for (const inst of project.browser?.instances ?? []) {
    if (inst.provider?.name) names.add(inst.provider.name)
  }
  if (names.size > 1) throw new Error(`Multiple browser providers in one project: ${[...names].join(', ')}`)
}

Type guard

function hasUniformProvider(project: any): boolean {
  const names = new Set<string>()
  if (project.browser?.provider?.name) names.add(project.browser.provider.name)
  for (const inst of project.browser?.instances ?? []) if (inst.provider?.name) names.add(inst.provider.name)
  return names.size <= 1
}

Prevention

Set browser.provider once at the project level and omit per-instance providers.
Split mixed-provider setups into separate workspace projects.
Validate the provider set in a config sanity check.

When it happens

Trigger: Set `browser: { enabled: true, instances: [{ browser: 'chromium', provider: playwright }, { browser: 'webkit', provider: webdriverio }] }` — two different providers in one project.

Common situations: Mixing Playwright and WebdriverIO in a single project; defining the provider on some instances but a different one at the project level; split-testing providers.

Related errors

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