vitest-dev/vitest · error · Error

vitest/browser can be imported only inside the Browser Mode.

Error message

vitest/browser can be imported only inside the Browser Mode. Your test is running in ${pool} pool. Make sure your regular tests are excluded from the "test.include" glob pattern.

What it means

The vitest/browser entry point (context.js) is designed to only load inside a browser-mode worker. At module-evaluation time it reads the worker pool name from globalThis.__vitest_worker__.ctx.pool. If a pool exists but is not the browser pool (e.g. 'forks' or 'threads'), this error fires with the pool name, telling you the test file was collected outside browser mode.

Source

Thrown at packages/vitest/browser/context.js:14

// Vitest resolves "vitest/browser" as a virtual module instead

// fake exports for static analysis
export const page = null
export const server = null
export const userEvent = null
export const cdp = null
export const commands = null
export const locators = null
export const utils = null

const pool = globalThis.__vitest_worker__?.ctx?.pool

throw new Error(
  // eslint-disable-next-line prefer-template
  'vitest/browser can be imported only inside the Browser Mode. '
  + (pool
    ? `Your test is running in ${pool} pool. Make sure your regular tests are excluded from the "test.include" glob pattern.`
    : 'Instead, it was imported outside of Vitest.'),
)

View on GitHub (pinned to 1fa9837ec2)

Solutions

1. Enable browser mode: set `test.browser.enabled = true` (and configure provider) in vitest.config.ts.
2. Exclude browser test files from the default (Node) test run via test.exclude, or use workspace projects to separate browser and Node configs.
3. Move browser-specific imports into files that are only collected under the browser project.

Example fix

// before — single config, browser file runs under forks pool:
// vitest.config.ts
export default defineConfig({ test: { } })

// after — enable browser mode:
export default defineConfig({
  test: { browser: { enabled: true, instances: [{ browser: 'chromium' }] } }
})

const pool = globalThis.__vitest_worker__?.ctx?.pool
if (pool !== 'browser') {
  // don't import vitest/browser in this context
}

When it happens

Trigger: A test file imports from 'vitest/browser' (using page, userEvent, locators, commands, etc.) but the test run uses the default forks/threads pool instead of the browser pool. Typically caused by the file matching test.include without browser-mode configuration.

Common situations: Adding browser tests to a project but forgetting to set `test.browser.enabled = true` or to scope browser imports to a separate project/config; the browser test file is also matched by the default test glob and runs in Node.

Related errors

• vitest/browser can be imported only inside the Browser Mode.
• The ${provider.name} provider does not support tracing.
• You've enabled headless mode for "preview" provider but it d
• vitest/browser can be imported only inside the Browser Mode.
• Unrecognized comparator ${comparator}

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