vitest-dev/vitest · error · Error

Browser Mode was enabled, but provider was not specified any

Error message

Browser Mode was enabled, but provider was not specified anywhere. See https://vitest.dev/guide/browser/#configuration

What it means

BrowserLoaderPlugin.config (browserLoader.ts:60) needs a browser provider exposing a serverFactory. It checks browser.provider, then any instance.provider; if none resolves (or the resolved provider has no serverFactory function), the browser pipeline can't boot. Browser mode therefore refuses to start instead of running headless without a provider.

Source

Thrown at packages/vitest/src/node/plugins/browserLoader.ts:60

    {
      name: 'vitest:browser:loader',
      // `pre` so the browser plugins injected via `applyToEnvironment` land before
      // Vite's internal resolver in the `client` environment (so e.g. the
      // `vitest/browser` virtual module wins over the node stub resolution).
      enforce: 'pre',
      async config(viteConfig) {
        const browser = viteConfig.test?.browser
        if (!browser?.enabled) {
          return
        }
        // The provider can be configured at the project level or per instance
        // (e.g. connect mode). All instances in a project share one provider
        // (validated in `resolveTestConfig`), so any instance's server factory
        // builds the shared server.
        const provider = browser.provider
          ?? browser.instances?.find(instance => instance.provider)?.provider
        if (!provider || typeof provider.serverFactory !== 'function') {
          throw new Error(`Browser Mode was enabled, but provider was not specified anywhere. See https://vitest.dev/guide/browser/#configuration`)
        }
        const contribution = await provider.serverFactory()
        holder.contribution = contribution
        const browserConfig = await contribution.config(viteConfig, harness)
        return browserConfig
      },
      applyToEnvironment(environment) {
        const contribution = holder.contribution
        if (contribution && environment.name === 'client') {
          // `post` browser plugins are injected by `vitest:browser:loader:post`
          // instead, so they run after the `post` plugins of the main pipeline
          // rather than at this `pre` position. For example, the mocker's
          // `vitest:browser:esm-injector` must run after `vitest:mocks`, which is
          // added by the main pipeline and is not part of `contribution.plugins`.
          return sortPluginsByEnforce(
            contribution.plugins.filter(plugin => plugin.enforce !== 'post'),
          )
        }

View on GitHub (pinned to d568f8ce37)

Solutions

1. Set test.browser.provider to a supported name (e.g. 'playwright') or set provider on each browser.instances entry.
2. Install the matching provider package and follow https://vitest.dev/guide/browser/#configuration.
3. Verify the provider is registered and exposes serverFactory (check @vitest/browser core).

Example fix

// before
test: { browser: { enabled: true } }

// after
test: { browser: { enabled: true, provider: 'playwright', instances: [{ browser: 'chromium' }] } }

const provider = browser.provider ?? browser.instances?.find(i => i.provider)?.provider
if (!provider || typeof provider.serverFactory !== 'function') {
  throw new Error('Browser mode needs a configured provider with serverFactory')
}

function hasBrowserProvider(browser: any): boolean {
  const p = browser?.provider ?? browser?.instances?.find((i: any) => i.provider)?.provider
  return p != null && typeof p.serverFactory === 'function'
}

When it happens

Trigger: Setting test.browser.enabled = true without configuring test.browser.provider (and no browser.instances with a provider), or specifying a provider that doesn't expose serverFactory (e.g. not installed / wrong package).

Common situations: Enabling browser mode before installing @vitest/browser-provider-playwright/webdriverio; misspelling the provider name; using instances without per-instance provider in a multi-instance setup.

Related errors

• You've enabled headless mode for "preview" provider but it d
• All browser instances within a project must use the same pro
• The `browser.provider` configuration was changed to accept a
• The ${provider.name} provider does not support tracing.
• The ${context.provider.name} provider does not support traci

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