vitest-dev/vitest · error · Error

The browser configuration must have a "name" property. This

Error message

The browser configuration must have a "name" property. This is a bug in Vitest. Please, open a new issue with reproduction

What it means

After verifying the browser field, the expander (resolveProjects.ts:684-687) checks that instance.name is non-null. Name auto-resolution should always produce a name (it falls back to the browser engine), so a null name indicates a bug in Vitest's own resolution rather than a user config error. The message explicitly asks the user to file an issue with a reproduction.

Source

Thrown at packages/vitest/src/node/projects/resolveProjects.ts:686

    }

    // Keep the parent in the entry list as `hidden` so a `TestProject` is
    // created (instances link to it via `_parent` for the browser provider).
    // The parent's name is removed from `names` because the instance names
    // take its place in the user-facing project list.
    names.delete(parentName)
    result.push({ ...entry, hidden: true })

    filteredInstances.forEach((instance, index) => {
      const browser = instance.browser
      if (!browser) {
        const nth = index + 1
        const ending = nth === 2 ? 'nd' : nth === 3 ? 'rd' : 'th'
        throw new Error(`The browser configuration must have a "browser" property. The ${nth}${ending} item in "browser.instances" doesn't have it. Make sure your${projectConfig.name ? ` "${projectConfig.name}"` : ''} configuration is correct.`)
      }
      const name = instance.name
      if (name == null) {
        throw new Error(`The browser configuration must have a "name" property. This is a bug in Vitest. Please, open a new issue with reproduction`)
      }
      if (instance.provider?.name != null && projectConfig.browser.provider?.name != null && instance.provider?.name !== projectConfig.browser.provider?.name) {
        throw new Error(`The instance cannot have a different provider from its parent. The "${name}" instance specifies "${instance.provider?.name}" provider, but its parent has a "${projectConfig.browser.provider?.name}" provider.`)
      }

      const provider = instance.provider?.name ?? projectConfig.browser.provider?.name ?? 'preview'

      // Browser-mode CDP only features:
      if (provider === 'preview' || !isChromiumName(provider, browser)) {
        const browserConfig = `
{
  browser: {
    provider: ${provider}(),
    instances: [
      ${(filteredInstances || []).map(i => `{ browser: '${i.browser}' }`).join(',\n      ')}
    ],
  },
}

View on GitHub (pinned to d568f8ce37)

Solutions

1. Set an explicit `name` on every browser instance to bypass the auto-resolution path.
2. Upgrade or downgrade Vitest to a version where the bug is fixed; check the issue tracker with the message.
3. File a Vitest issue with the minimal config that reproduces it, as the message requests.
4. Audit any plugins that touch config.test.browser.instances for mutations that null out name.

Example fix

// workaround: always set name explicitly
test: { browser: { enabled: true, provider: 'playwright', instances: [
  { browser: 'chromium', name: 'chromium' },
] } }

for (const inst of config.browser.instances) {
  if (inst.name == null) inst.name = inst.browser // force a name to bypass the buggy path
}

function instanceHasName(inst: unknown): inst is { name: string } {
  return !!inst && typeof (inst as any).name === 'string'
}

When it happens

Trigger: A code path where resolveProjectName / instance normalization returns null or undefined for a browser instance; an internal mutation that deletes instance.name before expansion; type drift where instance.name is typed string but runtime is null.

Common situations: Almost never seen in practice; if hit, it's typically after upgrading Vitest across a major version where the instance shape changed, or when a third-party plugin mutates browser.instances.

Related errors

• Cannot define a nested project for a ${browser} browser. The
• "browser.instances" was set in the config, but the array is
• The browser server was not initialized${project.name ? ` for
• Orchestrator not found for session ${sessionId}. This is a b
• Unexpected empty queue

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