vitest-dev/vitest · error · Error

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

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

The preview provider opens a real headed browser window for manual debugging; it does not implement headless execution. Its constructor checks `project.config.browser.headless` and throws immediately if headless is enabled, pointing you to playwright or webdriverio which do support headless. This fails at provider construction (startup), before any test runs.

Solutions

1. Remove `headless: true` when using the preview provider (it is headed only).
2. Switch provider to 'playwright' or 'webdriverio' if you need headless runs.
3. Keep separate config presets for local (preview) vs CI (playwright headless).

Example fix

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

// after - option A: keep preview, drop headless
export default defineConfig({ test: { browser: { provider: 'preview' } } })
// after - option B: stay headless, switch provider
export default defineConfig({ test: { browser: { provider: 'playwright', headless: true } } })

const provider = process.env.CI ? 'playwright' : 'preview'
const headless = !!process.env.CI

export default defineConfig({
  test: {
    browser: {
      provider,
      // preview does not support headless; only set it for playwright
      ...(provider === 'playwright' ? { headless } : {}),
    },
  },
})

function supportsHeadless(provider: string): boolean {
  return provider === 'playwright' || provider === 'webdriverio'
}

When it happens

Trigger: Configuring `browser: { provider: 'preview', headless: true }` (or setting `--headless` with preview). Common when copy-pasting a playwright config and only changing the provider name.

Common situations: CI environments where headless is the default; switching from playwright to preview without dropping the headless flag; sharing a config object across providers.

Related errors

• All browser instances within a project must use the same…
• browser is not initialized
• Browser Mode requires the "provider" to always be specified.
• Browser Mode was enabled, but provider was not specified…
• Method "elementLocator" is not supported by the

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/beb68d82f031baa5. Report an issue: GitHub.

Appendix: 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 1fa9837ec2)