vitest-dev/vitest · error · Error

Cannot define a nested project for a

Error message

Cannot define a nested project for a ${browser} browser. The project name "${name}" was already defined. If you have multiple instances for the same browser, make sure to define a custom "name". All projects should have unique names. Make sure your configuration is correct.

What it means

Every browser instance becomes a distinct nested project and is registered in a shared `names` set. If two instances resolve to the same project name, the second registration is rejected. The default name is derived from the browser (plus instance fields), so two instances of the same browser without explicit `name` values collide.

Solutions

Give each colliding browser instance a unique `name` field.
Remove the duplicate instance if it was unintended.
If you need the same browser twice, distinguish them by `name` (and optionally `headless`/launch options).

Example fix

// before
browser: {
  provider: 'playwright',
  instances: [
    { browser: 'chromium', headless: false },
    { browser: 'chromium', headless: true },
  ],
}

// after
browser: {
  provider: 'playwright',
  instances: [
    { name: 'chromium-headed', browser: 'chromium', headless: false },
    { name: 'chromium-headless', browser: 'chromium', headless: true },
  ],
}

Defensive patterns

Strategy: validation

Validate before calling

// Verify browser instance names are unique before starting Vitest.
function assertUniqueBrowserInstances(browser: { instances?: Array<{ name?: string; browser: string }> }) {
  const seen = new Set<string>()
  for (const i of browser.instances ?? []) {
    const name = i.name ?? i.browser
    if (seen.has(name)) {
      throw new Error(`Duplicate browser instance name '${name}'. Set a unique "name" on each instance.`)
    }
    seen.add(name)
  }
}

Prevention

Always set an explicit `name` when defining more than one instance per browser.
Add a unit test over your config that asserts all project (and instance) names are unique.

When it happens

Trigger: `names.has(name)` is true inside the per-instance loop after `name = instance.name`. Common: `instances: [{ browser: 'chromium' }, { browser: 'chromium' }]`, or two instances whose explicit `name` is identical.

Common situations: Running the same browser in parallel (e.g. one headed, one headless); copy-pasting an instance block and forgetting to set a unique `name`.

Related errors

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

Appendix: source

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

            `@vitest/coverage-v8 does not work with\n${browserConfig}\n`
            + `\nUse either:\n${correctExample}`
            + `\n\n...or change your coverage provider to:\n${coverageExample}\n`,
          )
        }

        if (globalConfig.inspect || globalConfig.inspectBrk) {
          const inspectOption = `--inspect${globalConfig.inspectBrk ? '-brk' : ''}`

          throw new Error(
            `${inspectOption} does not work with\n${browserConfig}\n`
            + `\nUse either:\n${correctExample}`
            + `\n\n...or disable ${inspectOption}\n`,
          )
        }
      }

      if (names.has(name)) {
        throw new Error(
          [
            `Cannot define a nested project for a ${browser} browser. The project name "${name}" was already defined. `,
            'If you have multiple instances for the same browser, make sure to define a custom "name". ',
            'All projects should have unique names. Make sure your configuration is correct.',
          ].join(''),
        )
      }
      names.add(name)

      const clonedConfig = cloneProjectConfigForBrowserInstance(projectConfig, instance)
      clonedConfig.name = name

      result.push({
        viteConfig, // shared with parent
        projectConfig: clonedConfig,
        ancestors: entry.ancestors,
      })
    })

View on GitHub (pinned to 1fa9837ec2)