vitest-dev/vitest · error · Error

Browser name is required. Please, set…

Error message

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

What it means

getBrowserProvider reads project.config.browser.name and throws if it is falsy when instances are used. Each browser instance must specify which browser it targets (chromium, firefox, webkit, edge, ...), because the provider needs a concrete target to spawn. The leading `[projectName]` is included if the project is named, to disambiguate multi-project setups.

Solutions

1. Set the `browser` field on every entry of test.browser.instances (e.g. 'chromium', 'firefox', 'webkit').
2. If you set browser.name at the top level, ensure it is not overridden to undefined inside an instance.
3. Validate the instances array at config load time, before Vitest starts.

Example fix

// before
test: { browser: { instances: [ { name: 'mobile', browser: undefined } ] } }
// after
test: { browser: { instances: [ { name: 'mobile', browser: 'chromium' } ] } }

function everyInstanceHasBrowser(instances: { browser?: string }[]): boolean {
  return instances.every(i => typeof i.browser === 'string' && i.browser.length > 0)
}

function isBrowserName(name: unknown): name is string {
  return typeof name === 'string' && ['chromium','firefox','webkit','edge'].includes(name)
}

When it happens

Trigger: Configuring test.browser.instances without a `browser` field on one or more instances; constructing instances programmatically and omitting the browser name; resolving browser.name from a CLI flag that came through empty.

Common situations: Multi-browser matrix configs where one instance entry was copy-pasted without its browser field; environment-driven configs that conditionally set the browser and fall through to undefined; upgrading to a version that started enforcing instances[].browser.

Related errors

• The browser configuration must have a "browser" property…
• The instance cannot have a different provider from its…
• All browser instances within a project must use the same…
• "browser.instances" was set in the config, but the array is…
• Browser provider is not defined for the project

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

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