vitest-dev/vitest · error · Error

Browser is not initialized

Error message

Browser is not initialized

What it means

Thrown by PreviewBrowserProvider.openPage when this.project.browser is undefined. openPage reads this.project.browser.vite.config.server to open the user's browser; if the project's browser orchestration layer was never initialized (e.g. browser mode not enabled or init order broken), the access fails.

Source

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

      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')
    }
    const options = this.project.browser.vite.config.server
    const _open = options.open
    options.open = url
    this.project.browser.vite.openBrowser()
    options.open = _open
  }

  async close(): Promise<void> {}
}

declare module 'vitest/browser' {
  export interface UserEventClickOptions extends SelectorOptions {}
  export interface UserEventHoverOptions extends SelectorOptions {}
  export interface UserEventFillOptions extends SelectorOptions {}
  export interface UserEventSelectOptions extends SelectorOptions {}
  export interface UserEventClearOptions extends SelectorOptions {}
  export interface UserEventDoubleClickOptions extends SelectorOptions {}

View on GitHub (pinned to d568f8ce37)

Solutions

1. Let Vitest's runner manage provider lifecycle; do not call openPage manually before init completes.
2. Ensure browser mode is correctly configured (projects with browser enabled) so project.browser is populated.
3. Check earlier logs for a failed init/openBrowser that left project.browser unset.
4. Upgrade Vitest packages together so the browser manager contract matches the provider.

Example fix

// before (manual/early call)
const provider = new PreviewBrowserProvider(project)
await provider.openPage('s', url) // project.browser is undefined

// after (let Vitest init first, then openPage is called by the runner)
// ensure project.browser is set by the runner before any openPage call

if (!project.browser) {
  throw new Error('project.browser is not initialized; cannot open preview page')
}
await provider.openPage(sessionId, url)

function browserInitialized(p: TestProject): boolean {
  return p.browser !== undefined && p.browser !== null
}

When it happens

Trigger: Calling provider.openPage before the project browser manager is initialized, running the preview provider without proper browser mode setup, or invoking openPage on a provider whose init was skipped/failed.

Common situations: Manually driving the preview provider outside Vitest's normal lifecycle, a partial init where openBrowser/init threw earlier, or version skew where the browser manager contract changed.

Related errors

• You've enabled headless mode for "preview" provider but it d
• The ${provider.name} provider does not support tracing.
• The ${context.provider.name} provider does not support traci
• provider ${context.provider.name} is not supported
• Page "${sessionId}" not found in ${this.browserName} browser

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