Vitest received --browser flag, but no project had a…

Error message

Vitest received --browser flag, but no project had a browser configuration.

What it means

After resolving all workspace projects, Vitest checks whether the CLI requested browser mode (`resolved.cliOptions.browser.enabled`). If none of the resolved projects has `config.browser.enabled === true`, the global flag has nothing to attach to and Vitest aborts instead of silently running node tests.

Solutions

Add `test.browser.enabled: true` (and at least one `instances` entry) to the project you intend to run in the browser.
Drop `--browser` from the CLI/script when running node-only projects.
Confirm your workspace config is actually being picked up (check `vitest --showConfig` or the resolved projects list).

Example fix

// before
vitest --browser   # no project has browser.enabled
// after
// vitest.config.ts
export default defineConfig({
  test: { browser: { enabled: true, instances: [{ browser: 'chromium' }] } },
})

Defensive patterns

Strategy: validation

Validate before calling

const cliBrowser = process.argv.includes('--browser')
const hasBrowserProject = (workspace: any[]) => workspace.some(p => p?.test?.browser?.enabled)
if (cliBrowser && !hasBrowserProject(projects)) {
  throw new Error('--browser was passed but no project enables browser mode.')
}

Type guard

function anyProjectEnablesBrowser(projects: any[]): boolean {
  return projects.some(p => p?.test?.browser?.enabled === true)
}

Prevention

Gate the `--browser` flag in scripts that are only used by browser-enabled repos.
Run `vitest list` after workspace changes to confirm the browser project resolves.

When it happens

Trigger: Passing `--browser` on the CLI when no project config sets `browser.enabled: true`; running `vitest --browser` in a fresh repo without browser setup.

Common situations: A script that always passes `--browser` reused on a non-browser project; partial migration where browser config lives in a workspace file that is not being loaded.

Related errors

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

Appendix: source

Thrown at packages/vitest/src/node/core.ts:416

        injectTestProjects: this.injectTestProject,
        defineCacheKeyGenerator: callback => this._fsCache.defineCacheKeyGenerator(callback),
        /**
         * @deprecated Use `defineCacheKeyGenerator` instead.
         */
        experimental_defineCacheKeyGenerator: (callback) => {
          if (!this._warnedExperimentalCacheKeyGenerator) {
            this._warnedExperimentalCacheKeyGenerator = true
            this.logger.deprecate('`experimental_defineCacheKeyGenerator` is deprecated. Use `defineCacheKeyGenerator` instead.')
          }
          this._fsCache.defineCacheKeyGenerator(callback)
        },
      }))
    }))

    if (resolved.cliOptions.browser?.enabled) {
      const browserProjects = this.projects.filter(p => p.config.browser.enabled)
      if (!browserProjects.length) {
        throw new Error(`Vitest received --browser flag, but no project had a browser configuration.`)
      }
    }
    if (!this.projects.length) {
      const filter = toArray(resolved.project).join('", "')
      if (filter) {
        throw new Error(`No projects matched the filter "${filter}".`)
      }
      else {
        let error = `Vitest wasn't able to resolve any project.`
        if (resolved.browser.enabled && !resolved.browser.instances?.length) {
          error += ` Please, check that you specified the "browser.instances" option.`
        }
        throw new Error(error)
      }
    }

    if (!this.coreWorkspaceProject) {
      this.coreWorkspaceProject = TestProject._createBasicProject(this)

View on GitHub (pinned to 1fa9837ec2)