{"id":"beb68d82f031baa5","repo":"vitest-dev/vitest","slug":"you-ve-enabled-headless-mode-for-preview-provide","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser-preview/src/preview.ts","lineNumber":32,"sourceCode":"}\n\nexport class PreviewBrowserProvider implements BrowserProvider {\n  public name = 'preview' as const\n  public supportsParallelism: boolean = false\n  private project!: TestProject\n  private open = false\n\n  public distRoot: string = distRoot\n\n  public initScripts: string[] = [\n    resolve(distRoot, 'locators.js'),\n  ]\n\n  constructor(project: TestProject) {\n    this.project = project\n    this.open = false\n    if (project.config.browser.headless) {\n      throw new Error(\n        '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',\n      )\n    }\n  }\n\n  isOpen(): boolean {\n    return this.open\n  }\n\n  getCommandsContext() {\n    return {}\n  }\n\n  async openPage(_sessionId: string, url: string): Promise<void> {\n    this.open = true\n    this.project.vitest.logger.log(`Browser runner started at ${url}\\n`)\n    if (!this.project.browser) {\n      throw new Error('Browser is not initialized')","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/browser-preview/src/preview.ts#L14-L50","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Remove headless (or set it false) when using the preview provider.","Switch provider to 'playwright' or 'webdriverio' for headless runs.","Drive headless from an env var so local (preview) and CI (playwright) differ: provider: process.env.CI ? 'playwright' : 'preview'."],"exampleFix":"// before\nexport default defineConfig({\n  test: { browser: { provider: 'preview', headless: true } },\n})\n\n// after\nexport default defineConfig({\n  test: {\n    browser: {\n      provider: process.env.CI ? 'playwright' : 'preview',\n      headless: !!process.env.CI,\n    },\n  },\n})","handlingStrategy":"validation","validationCode":"if (config.browser?.provider === 'preview' && config.browser?.headless) {\n  throw new Error('preview provider cannot run headless; use playwright or webdriverio')\n}","typeGuard":"function headlessCompatibleProvider(name: string): boolean {\n  return name === 'playwright' || name === 'webdriverio'\n}","tryCatchPattern":null,"preventionTips":["Drive provider/headless from an env var so local uses preview and CI uses playwright.","Never set headless: true with the preview provider.","Validate the provider/headless combination in vitest.config before running."],"tags":["browser","provider","preview","headless","config","vitest"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}