vitest-dev/vitest · error · Error

Browser Mode requires the "provider" to always be specified.

Error message

Browser Mode requires the "provider" to always be specified.

What it means

Thrown by getBrowserProvider when the resolved browser options have a null/undefined provider. The provider is the driver abstraction (playwright, webdriverio, or a custom factory) that actually launches and controls the browser; without one, Vitest cannot dispatch any browser command. This is a configuration-resolution failure, not a runtime race.

Solutions

Install the matching provider package (e.g. pnpm add -D @vitest/browser-provider-playwright) and ensure it is imported/registered.
Verify '@vitest/browser' is listed in test.browser and that the provider package version matches your vitest version.
Check Vite plugin ordering — the provider plugin must run during config resolution; inspect for a silently failing plugin in your vite/vitest config.
If using a custom provider, confirm its factory is wired into the providers map passed to the browser plugin.

Example fix

// before: no provider installed, browser tests run with bare @vitest/browser
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { browser: { enabled: true, name: 'chromium' } } })
// after
pnpm add -D @vitest/browser-provider-playwright playwright
export default defineConfig({ test: { browser: { enabled: true, name: 'chromium', provider: 'playwright' } } })

Defensive patterns

Strategy: validation

Validate before calling

// Before launching browser tests, confirm a provider resolved.
import { readFileSync } from 'node:fs'
function ensureBrowserProvider(cfg) {
  const provider = cfg.test?.browser?.provider
  if (!provider) {
    throw new Error('No test.browser.provider set — install @vitest/browser-provider-playwright and set provider: "playwright".')
  }
}
ensureBrowserProvider(require('./vitest.config.ts')) // adjust loader as needed

Type guard

// Narrow a provider candidate before assigning it.
function isBrowserProviderName(v): v is 'playwright' | 'webdriverio' {
  return v === 'playwright' || v === 'webdriverio'
}

Prevention

Always set test.browser.provider explicitly in config rather than relying on defaults.
Keep the provider package version aligned with your installed @vitest/browser version.
Add a startup smoke test that asserts the provider plugin is registered.

When it happens

Trigger: getBrowserProvider(options, project) is called with options.provider == null. This occurs when no browser provider plugin registered itself during Vite plugin setup, or the provider field on ResolvedBrowserOptions was never populated by the resolver.

Common situations: Missing the @vitest/browser-provider-playwright (or webdriverio) package; importing the browser package without the provider peer dependency; a version mismatch where the provider plugin's hooks don't run; a custom provider object that fails its own initialization silently.

Related errors

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

Appendix: source

Thrown at packages/browser/src/node/utils.ts:80

      name,
    )
  }
  return resolve(dir, '__screenshots__', base, name)
}

export async function getBrowserProvider(
  options: ResolvedBrowserOptions,
  project: TestProject,
): Promise<BrowserProvider> {
  const browser = project.config.browser.name
  const name = project.name ? `[${project.name}] ` : ''
  if (!browser) {
    throw new Error(
      `${name}Browser name is required. Please, set \`test.browser.instances[].browser\` option manually.`,
    )
  }
  if (options.provider == null) {
    throw new Error(`Browser Mode requires the "provider" to always be specified.`)
  }
  const supportedBrowsers = options.provider.supportedBrowser || []
  if (supportedBrowsers.length && !supportedBrowsers.includes(browser)) {
    throw new Error(
      `${name}Browser "${browser}" is not supported by the browser provider "${
        options.provider.name
      }". Supported browsers: ${supportedBrowsers.join(', ')}.`,
    )
  }
  if (typeof options.provider.providerFactory !== 'function') {
    throw new TypeError(`The "${name}" browser provider does not provide a "providerFactory" function. Received ${typeof options.provider.providerFactory}.`)
  }
  return options.provider.providerFactory(project)
}

export function slash(path: string): string {
  return path.replace(/\\/g, '/').replace(/\/+/g, '/')
}

View on GitHub (pinned to 1fa9837ec2)