All browser instances within a project must use the same…

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

Each Vitest project spawns one shared browser Vite server, so all `browser.instances` (plus the project-level `browser.provider`) must resolve to the same provider name AND the same server factory. This guard catches both the obvious case (e.g. `playwright` alongside `webdriverio`) and the subtle case where the name matches but the factory reference differs (e.g. two different imported factory objects).

Solutions

Pick one provider for the whole project and reuse that exact factory reference on every instance.
If you genuinely need two providers, split the instances into separate Vitest projects.
Centralise the provider import in a single module and re-export it everywhere it is referenced.

Example fix

// before
browser: {
  provider: playwright(),
  instances: [
    { browser: 'chromium' },
    { browser: 'firefox', provider: webdriverio() },
  ],
}
// after (split projects)
projects: [
  { test: { browser: { provider: playwright(), instances: [{ browser: 'chromium' }] } } },
  { test: { browser: { provider: webdriverio(), instances: [{ browser: 'firefox' }] } } },
]

Defensive patterns

Strategy: type-guard

Validate before calling

import { playwright } from '@vitest/browser-playwright'
const provider = playwright()
const instances = [{ browser: 'chromium' as const }, { browser: 'firefox' as const }]
// ensure every instance uses the SAME provider reference
const validated = instances.map(i => ({ ...i, provider }))
export default defineConfig({ test: { browser: { provider, instances: validated } } })

Type guard

function hasUniformProvider(instances: any[], projectProvider: any): boolean {
  const factory = projectProvider?.serverFactory
  return instances.every(i => i?.provider?.serverFactory === factory || i.provider == null)
}

Prevention

Define the provider once at the top of the config and reuse the same reference.
If two providers are genuinely needed, split them into separate `projects` entries.

When it happens

Trigger: Mixing `browser.provider: playwright()` with an instance carrying `provider: webdriverio()`; importing the provider factory in two different files and assigning different references; instances sourced from different packages despite the same nominal name.

Common situations: Multi-browser smoke tests where someone added a second provider per-instance instead of splitting projects; refactor that moved the provider import.

Related errors

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

Appendix: source

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

    // 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 1fa9837ec2)