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 options.provider is null or undefined. The 'provider' option (e.g. 'playwright' or 'webdriverio') tells Vitest which driver implementation to use for launching the browser; it is mandatory whenever browser mode is active.

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 d568f8ce37)

Solutions

1. Set test.browser.provider to 'playwright' or 'webdriverio' in your vitest config.
2. Install the matching driver package (e.g. pnpm add -D @vitest/browser-playwright).
3. If the package is installed, check the provider name spelling and that node_modules is intact (rerun pnpm install).

Example fix

// before
export default defineConfig({
  test: { browser: { enabled: true, instances: [{ browser: 'chromium' }] } },
})
// after
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
})

import { existsSync } from 'node:fs'
// ensure the driver package is resolvable before running
const ok = ['@vitest/browser-playwright', '@vitest/browser-webdriverio']
  .some(p => import.meta.resolve?.(p))
if (!ok) throw new Error('Install a browser driver provider package')

function hasProvider(opts: any): opts is { provider: NonNullable<any> } {
  return opts != null && opts.provider != null
}

When it happens

Trigger: Enabling test.browser without specifying test.browser.provider, or the provider resolution returning null because the provider package is not installed or failed to load.

Common situations: Forgetting the provider key after enabling browser mode; installing @vitest/browser but not the driver (e.g. @vitest/browser-playwright); a typo in the provider name preventing module resolution so it resolves to undefined.

Related errors

• You've enabled headless mode for "preview" provider but it d
• ${name}Browser name is required. Please, set `test.browser.i
• ${name}Browser "${browser}" is not supported by the browser
• The "${name}" browser provider does not provide a "providerF
• Access denied to "${path}". See Vite config documentation fo

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