vitest browser mode failed to start playwright provider

TL;DR

Vitest browser mode needs two separate installs: the provider package @vitest/browser-playwright and the Playwright browser binaries. Most startup failures are one of those missing, or the config naming a provider that isnt installed. Install both, confirm the config import, then rerun.

Error

Error: Failed to start browser provider "playwright". Make sure the provider package is installed and the browser binaries are present.

Steps

1. Run npm ls @vitest/browser-playwright (or the pnpm/yarn equivalent) to confirm the provider package is installed. Expected: a version number is listed, not "empty" or "missing".
2. If it is missing, install it: npm install -D @vitest/browser-playwright. Expected: the install completes with no errors.
3. Install the browser binaries: npx playwright install chromium (swap in firefox or webkit to match your instances config). Expected: the download finishes and reports a browser path.
4. Open vitest.config and confirm the browser block imports the provider (provider: playwright() from @vitest/browser-playwright) and sets browser.enabled to true. Expected: the config loads with no import errors when vitest starts.
5. Run npx vitest --browser --browser.headless on a single test file. Expected: the browser launches and the test runs, so you see a pass or a test failure instead of a provider startup error.

When to use

• Vitest with browser mode enabled fails before any test runs, and the error names the playwright provider.
• You just turned on browser mode and never installed the browser binaries.
• CI fails on provider startup while local runs work (binaries not cached in CI).

When not to use

• Tests start but fail inside the browser (page errors, assertion failures); the provider already started fine.
• You use the webdriverio or preview provider; the package names and install steps differ.
• Plain vitest in node or jsdom fails; browser mode is not involved.

Tool compatibility

• Vitest 2.x and 3.x, with @vitest/browser-playwright on the same major version as Vitest.
• Playwright 1.4x and newer; chromium, firefox, and webkit browser instances.

Variant phrasings

browser provider failed to initialize

Same startup phase, different wording. The checklist is identical: provider package installed, binaries present, config import correct.

Playwright browser not found when running vitest --browser

The binaries step is the fix. On Linux CI add system deps with npx playwright install --with-deps chromium so the browser can actually launch.

vitest browser mode worked yesterday and broke today

Suspect a version bump: Vitest and the provider package must stay on matching majors after upgrades.

Why it happens

Vitest keeps browser support out of the core package, so the provider and the real browser binaries are separate installs. If either is missing, or the config names a provider whose package isnt installed, startup dies before the first test file loads.

Edge cases

• Version skew between vitest and @vitest/browser-playwright produces cryptic startup errors; pin both to the same major.
• On Linux CI, browsers need OS libraries; the --with-deps flag pulls them in.
• Running as root in Docker: Chromium refuses to start without sandbox-disabling launch args, which go in the browser.instances launch options.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_PQIa0hygDH1YGzINJj0efw