vitest-dev/vitest · error · TypeError

The `browser.provider` configuration was changed to accept a

Error message

The `browser.provider` configuration was changed to accept a factory instead of a string. Add an import of "${resolved.browser.provider}" from "${source}" instead. See: https://vitest.dev/config/browser/provider

What it means

Vitest changed `browser.provider` from a string identifier (e.g. `'playwright'`) to a factory function imported from a package. The check at resolveConfig.ts:861 detects a string and throws, instructing you to import the provider and pass the factory instead, with a link to the migration docs.

Source

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

    )
  }

  if (resolved.inspector.enabled) {
    resolved.browser.trackUnhandledErrors ??= false
  }

  resolved.browser.viewport ??= {} as any
  resolved.browser.viewport.width ??= 414
  resolved.browser.viewport.height ??= 896

  resolved.browser.locators ??= {} as any
  resolved.browser.locators.testIdAttribute ??= 'data-testid'
  resolved.browser.locators.exact ??= true
  resolved.browser.locators.errorFormat ??= 'all'

  if (typeof resolved.browser.provider === 'string') {
    const source = `@vitest/browser-${resolved.browser.provider}`
    throw new TypeError(
      'The `browser.provider` configuration was changed to accept a factory instead of a string. '
      + `Add an import of "${resolved.browser.provider}" from "${source}" instead. See: https://vitest.dev/config/browser/provider`,
    )
  }

  const isPreview = resolved.browser.provider?.name === 'preview'

  if (!isPreview && resolved.browser.enabled && stdProvider === 'stackblitz') {
    throw new Error(`stackblitz environment does not support the ${resolved.browser.provider?.name} provider. Please, use "@vitest/browser-preview" instead.`)
  }
  if (isPreview && resolved.browser.screenshotFailures === true) {
    console.warn(c.yellow(
      [
        `Browser provider "preview" doesn't support screenshots, `,
        `so "browser.screenshotFailures" option is forcefully disabled. `,
        `Set "browser.screenshotFailures" to false or remove it from the config to suppress this warning.`,
      ].join(''),
    ))

View on GitHub (pinned to d568f8ce37)

Solutions

Import the provider factory and pass it: `import { playwright } from '@vitest/browser-playwright'; browser: { provider: playwright }`.
If the provider name in the error is something else, import from the corresponding `@vitest/browser-<name>` package.
Update the `@vitest/browser-*` package to the version matching your Vitest.

Example fix

// before
import { defineConfig } from 'vitest/config'
export default defineConfig({ test: { browser: { enabled: true, provider: 'playwright' } } })
// after
import { defineConfig } from 'vitest/config'
import { playwright } from '@vitest/browser-playwright'
export default defineConfig({ test: { browser: { enabled: true, provider: playwright } } })

Defensive patterns

Strategy: type-guard

Validate before calling

function assertBrowserProviderIsFactory(browser: any) {
  if (browser?.provider != null && typeof browser.provider === 'string') {
    throw new Error(`browser.provider must be a factory, not a string. Import from @vitest/browser-${browser.provider}.`)
  }
}

Type guard

function isProviderFactory(provider: unknown): provider is { name: string; serverFactory: unknown } {
  return typeof provider === 'object' && provider !== null && typeof (provider as any).name === 'string'
}

Prevention

After upgrading Vitest, grep configs for `provider:` string literals.
Import the provider factory from its @vitest/browser-* package.
Pin the browser provider package version to match Vitest.

When it happens

Trigger: Set `browser: { provider: 'playwright' }` (a string) in a config targeting the current Vitest version.

Common situations: Upgrading Vitest across the major version that changed the provider API; copy-pasting config from old docs or examples.

Related errors

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