vitest-dev/vitest · error · Error

Browser is not initialized

Error message

Browser is not initialized

What it means

PreviewBrowserProvider.openPage delegates to `this.project.browser.vite.openBrowser()` to launch the headed window. It first asserts `this.project.browser` is set — if the BrowserPlugin has not initialized the browser object yet, openPage throws. This indicates a lifecycle ordering problem: openPage was called before browser initialization completed.

Solutions

1. Do not call openPage manually; let vitest's browser plugin drive it after initialization.
2. Ensure the browser plugin is properly registered in the vite config for the project.
3. If extending vitest, await project initialization before invoking provider methods.
4. Check vitest version compatibility — this should be wired internally; if seen, file an issue.

// not user-callable in normal flows — if integrating vitest programmatically:
if (!project.browser) {
  throw new Error('Browser plugin must initialize before openPage is called')
}

function isBrowserReady(project: { browser?: unknown }): boolean {
  return !!project.browser
}

When it happens

Trigger: openPage invoked before the browser plugin's configureServer/initialization has run; custom orchestration that calls openPage directly; a race during vitest startup where the preview provider is asked to open before `project.browser` is assigned.

Common situations: Plugin load order issues; custom test runner integrating vitest incorrectly; partial initialization after a config error; preview provider used outside the standard vitest lifecycle.

Related errors

• stopChunkTrace cannot be called outside of the test file.
• This command can only be called inside a test file.
• browser is not initialized
• Browser provider is not defined for the project
• Can't find browser origin URL for project

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

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