vitest-dev/vitest · error · Error

"browser.instances" was set in the config, but the array is

Error message

"browser.instances" was set in the config, but the array is empty. Define at least one browser config. The "browser.name" was set to "${browser.name}" which filtered all configs (${instances.map(c => c.browser).join(', ')}). Did you mean to use another name?

What it means

When `browser.name` is set (often via `--browser=chromium`), Vitest filters `browser.instances` to those whose `browser` field matches that name. If the filter removes every instance, the config is left with no runnable browser, so resolveConfig.ts:436 throws with the list of configured browser names to help you spot the mismatch.

Source

Thrown at packages/vitest/src/node/config/resolveConfig.ts:437

      )
    }
    browser.provider ??= browser.instances.find(instance => instance.provider)?.provider

    // use `chromium` by default when the preview provider is specified
    // for a smoother experience. if chromium is not available, it will
    // open the default browser anyway
    if (!browser.instances.length && browser.provider?.name === 'preview') {
      browser.instances = [{ browser: 'chromium' }]
    }

    if (browser.name && instances?.length) {
      // --browser=chromium filters configs to a single one
      browser.instances = browser.instances.filter(instance => instance.browser === browser.name)

      // if `instances` were defined, but now they are empty,
      // let's throw an error because the filter is invalid
      if (!browser.instances.length) {
        throw new Error([
          `"browser.instances" was set in the config, but the array is empty. Define at least one browser config.`,
          ` The "browser.name" was set to "${browser.name}" which filtered all configs (${instances.map(c => c.browser).join(', ')}). Did you mean to use another name?`,
        ].join(''))
      }
    }

    browser.instances.forEach((instance) => {
      instance.name ??= resolved.name
        ? `${resolved.name} (${instance.browser})`
        : instance.browser
    })
  }

  if (resolved.coverage.enabled && resolved.coverage.provider === 'istanbul' && resolved.experimental?.viteModuleRunner === false) {
    throw new Error(`"Istanbul" coverage provider is not compatible with "experimental.viteModuleRunner: false". Please, enable "viteModuleRunner" or switch to "v8" coverage provider.`)
  }

  if (browser.enabled && resolved.detectAsyncLeaks) {

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass a name that matches one of your configured instances: `--browser=firefox`.
2. Add an instance for the browser you want to target: `instances: [{ browser: 'chromium' }, ...]`.
3. Drop --browser to run all configured instances, or remove the filter to let Vitest pick.

Example fix

// config: instances: [{ browser: 'firefox' }]
# before
vitest --browser=chromium
# after
vitest --browser=firefox

function assertBrowserNameMatchesInstance(opts: { name?: string; instances?: { browser: string }[] }) {
  if (opts.name && opts.instances?.length && !opts.instances.some(i => i.browser === opts.name)) {
    throw new Error(`--browser=${opts.name} matches no instance (${opts.instances.map(i => i.browser).join(', ')})`)
  }
}

function browserNameHasMatch(opts: { name?: string; instances?: { browser: string }[] }): boolean {
  return !opts.name || !opts.instances?.length || opts.instances.some(i => i.browser === opts.name)
}

When it happens

Trigger: Config defines `browser.instances: [{ browser: 'firefox' }]` and you run `vitest --browser=chromium`. The filter at line 432 removes the firefox instance, leaving an empty array.

Common situations: Passing --browser with a name that doesn't match any defined instance; typo'd browser name; defaulting to chromium when only webkit/firefox are configured.

Related errors

• Vitest received --browser flag, but no project had a browser
• You've enabled headless mode for "preview" provider but it d
• vitest/browser can be imported only inside the Browser Mode.
• Looks like you set "test.environment" to "browser". To enabl
• All browser instances within a project must use the same pro

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