vitest-dev/vitest · 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=chromium` (or `browser.name`) is supplied, Vitest filters the configured `browser.instances` down to those whose `browser` field matches that name. If the filter removes every instance, the config is left with an empty array, which is almost always a typo. Vitest names the requested browser and lists the originally-configured browser values so the mismatch is obvious.

Solutions

1. Use the canonical engine name (`chromium`, `firefox`, `webkit`) on both the instance and the filter.
2. Add an instance whose `browser` matches the requested name.
3. Drop `--browser=...` if you want to run every configured instance.

Example fix

# before
vitest --browser=firefox  # but only chromium is configured
# after
vitest --browser=chromium
# or extend config
browser: { instances: [{ browser: 'chromium' }, { browser: 'firefox' }] }

const instances = [{ browser: 'chromium' }, { browser: 'firefox' }]
const requested = process.env.BROWSER // e.g. 'firefox'
if (requested && !instances.some(i => i.browser === requested)) {
  throw new Error(`--browser=${requested} matches none of ${instances.map(i => i.browser).join(', ')}`)
}

function isKnownBrowserName(name: string): name is 'chromium' | 'firefox' | 'webkit' {
  return name === 'chromium' || name === 'firefox' || name === 'webkit'
}

When it happens

Trigger: `browser.instances: [{ browser: 'chromium' }]` combined with `--browser=firefox`; or a CLI override `--browser chrome` that does not match the canonical `'chromium'` string.

Common situations: CLI shorthand using a vendor name (`chrome`, `ff`) that does not match Playwright's canonical engine name; an instance list filtered against a stale `browser.name`.

Related errors

• All browser instances within a project must use the same…
• Browser name is required. Please, set…
• The browser configuration must have a "browser" property…
• The instance cannot have a different provider from its…
• Unknown value for "test.listTags

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

Appendix: source

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

      )
    }
    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 1fa9837ec2)