vitest-dev/vitest · error · Error

You've enabled headless mode for "preview" provider but it d

Error message

You've enabled headless mode for "preview" provider but it doesn't support it. Use "playwright" or "webdriverio" instead: https://vitest.dev/guide/browser/#configuration

What it means

Thrown in the PreviewBrowserProvider constructor when project.config.browser.headless is true. The 'preview' provider opens the user's real browser via Vite's openBrowser for manual inspection; it has no headless implementation. The error points the user to 'playwright' or 'webdriverio' for headless runs.

Source

Thrown at packages/browser-preview/src/preview.ts:32

}

export class PreviewBrowserProvider implements BrowserProvider {
  public name = 'preview' as const
  public supportsParallelism: boolean = false
  private project!: TestProject
  private open = false

  public distRoot: string = distRoot

  public initScripts: string[] = [
    resolve(distRoot, 'locators.js'),
  ]

  constructor(project: TestProject) {
    this.project = project
    this.open = false
    if (project.config.browser.headless) {
      throw new Error(
        'You\'ve enabled headless mode for "preview" provider but it doesn\'t support it. Use "playwright" or "webdriverio" instead: https://vitest.dev/guide/browser/#configuration',
      )
    }
  }

  isOpen(): boolean {
    return this.open
  }

  getCommandsContext() {
    return {}
  }

  async openPage(_sessionId: string, url: string): Promise<void> {
    this.open = true
    this.project.vitest.logger.log(`Browser runner started at ${url}\n`)
    if (!this.project.browser) {
      throw new Error('Browser is not initialized')

View on GitHub (pinned to d568f8ce37)

Solutions

1. Remove headless (or set it false) when using the preview provider.
2. Switch provider to 'playwright' or 'webdriverio' for headless runs.
3. Drive headless from an env var so local (preview) and CI (playwright) differ: provider: process.env.CI ? 'playwright' : 'preview'.

Example fix

// before
export default defineConfig({
  test: { browser: { provider: 'preview', headless: true } },
})

// after
export default defineConfig({
  test: {
    browser: {
      provider: process.env.CI ? 'playwright' : 'preview',
      headless: !!process.env.CI,
    },
  },
})

if (config.browser?.provider === 'preview' && config.browser?.headless) {
  throw new Error('preview provider cannot run headless; use playwright or webdriverio')
}

function headlessCompatibleProvider(name: string): boolean {
  return name === 'playwright' || name === 'webdriverio'
}

When it happens

Trigger: Configuring `browser: { provider: 'preview', headless: true }`, or setting headless globally while using the preview provider (e.g. via the --headless CLI flag or CI defaults).

Common situations: CI configs that default to headless, reusing a local config (preview) in CI, or a stale headless flag after switching providers from playwright to preview.

Related errors

• Browser is not initialized
• The ${provider.name} provider does not support tracing.
• The ${context.provider.name} provider does not support traci
• provider ${context.provider.name} is not supported
• vitest/browser can be imported only inside the Browser Mode.

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