vitest-dev/vitest · error · Error

${name}Browser name is required. Please, set `test.browser.i

Error message

${name}Browser name is required. Please, set `test.browser.instances[].browser` option manually.

What it means

Thrown by getBrowserProvider() when the resolved browser name is empty/falsy. Vitest's Browser Mode needs to know which browser engine to launch (chromium, firefox, webkit, etc.) for each project/instance. Without a name it cannot resolve a provider, so it aborts before any test runs.

Source

Thrown at packages/browser/src/node/utils.ts:75

  if (config.browser.screenshotDirectory) {
    return resolve(
      config.browser.screenshotDirectory,
      relative(config.root, dir),
      base,
      name,
    )
  }
  return resolve(dir, '__screenshots__', base, name)
}

export async function getBrowserProvider(
  options: ResolvedBrowserOptions,
  project: TestProject,
): Promise<BrowserProvider> {
  const browser = project.config.browser.name
  const name = project.name ? `[${project.name}] ` : ''
  if (!browser) {
    throw new Error(
      `${name}Browser name is required. Please, set \`test.browser.instances[].browser\` option manually.`,
    )
  }
  if (options.provider == null) {
    throw new Error(`Browser Mode requires the "provider" to always be specified.`)
  }
  const supportedBrowsers = options.provider.supportedBrowser || []
  if (supportedBrowsers.length && !supportedBrowsers.includes(browser)) {
    throw new Error(
      `${name}Browser "${browser}" is not supported by the browser provider "${
        options.provider.name
      }". Supported browsers: ${supportedBrowsers.join(', ')}.`,
    )
  }
  if (typeof options.provider.providerFactory !== 'function') {
    throw new TypeError(`The "${name}" browser provider does not provide a "providerFactory" function. Received ${typeof options.provider.providerFactory}.`)
  }
  return options.provider.providerFactory(project)

View on GitHub (pinned to d568f8ce37)

Solutions

1. Set test.browser.name to a supported browser (e.g. 'chromium') at the project level, OR
2. Add test.browser.instances[] entries each with a 'browser' field, e.g. { browser: 'chromium' }.
3. If using a custom project, ensure the name propagates from config.browser.instances[i].browser into config.browser.name.

Example fix

// before
export default defineConfig({
  test: {
    browser: { enabled: true, provider: 'playwright' }, // no browser name
  },
})
// after
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
})

// before running browser tests, verify each instance has a browser name
import { defineConfig } from 'vitest/config'
const cfg = defineConfig({})
const instances = cfg.test?.browser?.instances ?? []
for (const inst of instances) {
  if (!inst.browser) throw new Error(`instance missing 'browser': ${JSON.stringify(inst)}`)
}

function hasBrowserName(inst: unknown): inst is { browser: string } {
  return typeof inst === 'object' && inst !== null
    && typeof (inst as any).browser === 'string'
    && (inst as any).browser.length > 0
}

When it happens

Trigger: Calling browser tests where project.config.browser.name resolves to '' or undefined. This happens when you enable browser mode but omit the browser field, or define instances[] entries without a 'browser' key.

Common situations: Setting test.browser.enabled=true without instances or a top-level browser name; copy-pasting a config snippet that referenced a browser variable that was never defined; upgrading Vitest where instances[].browser became required.

Related errors

• ${name}Browser "${browser}" is not supported by the browser
• Browser Mode requires the "provider" to always be specified.
• Access denied to "${path}". See Vite config documentation fo
• Cannot modify file "${path}". File writing is disabled becau
• Cannot take a screenshot without a test path

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