{"record":{"id":"aa552a344572952d","repo":"vitest-dev/vitest","slug":"browser-mode-requires-the-provider-to-always-be","errorCode":null,"errorMessage":"Browser Mode requires the \"provider\" to always be specified.","messagePattern":"Browser Mode requires the \"provider\" to always be specified\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser/src/node/utils.ts","lineNumber":80,"sourceCode":"      name,\n    )\n  }\n  return resolve(dir, '__screenshots__', base, name)\n}\n\nexport async function getBrowserProvider(\n  options: ResolvedBrowserOptions,\n  project: TestProject,\n): Promise<BrowserProvider> {\n  const browser = project.config.browser.name\n  const name = project.name ? `[${project.name}] ` : ''\n  if (!browser) {\n    throw new Error(\n      `${name}Browser name is required. Please, set \\`test.browser.instances[].browser\\` option manually.`,\n    )\n  }\n  if (options.provider == null) {\n    throw new Error(`Browser Mode requires the \"provider\" to always be specified.`)\n  }\n  const supportedBrowsers = options.provider.supportedBrowser || []\n  if (supportedBrowsers.length && !supportedBrowsers.includes(browser)) {\n    throw new Error(\n      `${name}Browser \"${browser}\" is not supported by the browser provider \"${\n        options.provider.name\n      }\". Supported browsers: ${supportedBrowsers.join(', ')}.`,\n    )\n  }\n  if (typeof options.provider.providerFactory !== 'function') {\n    throw new TypeError(`The \"${name}\" browser provider does not provide a \"providerFactory\" function. Received ${typeof options.provider.providerFactory}.`)\n  }\n  return options.provider.providerFactory(project)\n}\n\nexport function slash(path: string): string {\n  return path.replace(/\\\\/g, '/').replace(/\\/+/g, '/')\n}","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/node/utils.ts#L62-L98","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: no provider installed, browser tests run with bare @vitest/browser\nimport { defineConfig } from 'vitest/config'\nexport default defineConfig({ test: { browser: { enabled: true, name: 'chromium' } } })\n// after\npnpm add -D @vitest/browser-provider-playwright playwright\nexport default defineConfig({ test: { browser: { enabled: true, name: 'chromium', provider: 'playwright' } } })","handlingStrategy":"validation","validationCode":"// Before launching browser tests, confirm a provider resolved.\nimport { readFileSync } from 'node:fs'\nfunction ensureBrowserProvider(cfg) {\n  const provider = cfg.test?.browser?.provider\n  if (!provider) {\n    throw new Error('No test.browser.provider set — install @vitest/browser-provider-playwright and set provider: \"playwright\".')\n  }\n}\nensureBrowserProvider(require('./vitest.config.ts')) // adjust loader as needed","typeGuard":"// Narrow a provider candidate before assigning it.\nfunction isBrowserProviderName(v): v is 'playwright' | 'webdriverio' {\n  return v === 'playwright' || v === 'webdriverio'\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["browser","config","provider","vitest"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}