vitest-dev/vitest · error · Error

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

Error message

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

What it means

The `--browser` CLI flag enables browser mode globally, but it does nothing unless at least one project in the workspace has `browser.enabled: true`. The check at core.ts:414-417 scans resolved projects for browser config and throws if none has it, so you discover the misconfiguration immediately rather than seeing zero browser tests run.

Source

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

        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 d568f8ce37)

Solutions

Enable browser mode in at least one project: `test: { browser: { enabled: true, instances: [{ browser: 'chromium' }] } }`.
If using a workspace, ensure the project with browser config is included (not filtered out by --project).
Drop --browser if you did not intend to run browser tests.

Example fix

// before — no browser config anywhere, run: vitest --browser
export default defineConfig({ test: { environment: 'node' } })
// after
export default defineConfig({ test: { browser: { enabled: true, instances: [{ browser: 'chromium' }] } } })

Defensive patterns

Strategy: validation

Validate before calling

function assertBrowserProjectExists(projects: { config: { browser: { enabled?: boolean } } }[], cliBrowserEnabled: boolean) {
  if (cliBrowserEnabled && !projects.some(p => p.config.browser.enabled)) {
    throw new Error('--browser requires at least one project with browser.enabled')
  }
}

Type guard

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

Prevention

Enable browser in a project before passing --browser.
Use a workspace project dedicated to browser tests.
Remove --browser for pure node test runs.

When it happens

Trigger: Run `vitest --browser` against a workspace where no project sets `test.browser.enabled = true`.

Common situations: Passing --browser expecting it to enable browser mode automatically; browser config commented out or in a different project than the one being run; misnamed config key.

Related errors

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