What causes "no browsers found in machineBrowsers" in cypress-io/cypress?

Install a supported browser on the machine (Chrome stable is the most reliable), then restart Cypress so the cache is rebuilt.

cypress-io/cypress · critical

no browsers found in machineBrowsers

Error message

no browsers found in machineBrowsers

What it means

Thrown by BrowserDataSource.machineBrowsers() when the launcher returns an empty browser array (browsers[0] is falsy at BrowserDataSource.ts:89). The result promise is cached on coreData.machineBrowsers and, on rejection, the catch handler clears the cache (sets it to null) and writes the error into coreData.diagnostics.error so the launchpad can surface it. The underlying list comes from ctx._apis.browserApi.getBrowsers() (the @packages/launcher scan). It means Cypress cannot find any browser it can drive on this machine.

Source

Thrown at packages/data-context/src/sources/BrowserDataSource.ts:89

    this.ctx.coreData.allBrowsers = Promise.resolve(_.concat(machineBrowsers, userBrowsers))

    return this.ctx.coreData.allBrowsers
  }

  /**
   * Gets the browsers from the machine, caching the Promise on the coreData
   * so we only look them up once
   */
  machineBrowsers () {
    if (this.ctx.coreData.machineBrowsers) {
      return this.ctx.coreData.machineBrowsers
    }

    const p = this.ctx._apis.browserApi.getBrowsers()

    return this.ctx.coreData.machineBrowsers = p.then(async (browsers) => {
      if (!browsers[0]) throw new Error('no browsers found in machineBrowsers')

      return browsers
    }).catch((e) => {
      this.ctx.update((coreData) => {
        coreData.machineBrowsers = null
        coreData.diagnostics.error = e
      })

      throw e
    })
  }

  idForBrowser (obj: FoundBrowser) {
    return `${obj.name}-${obj.family}-${obj.channel}`
  }

  isSelected (obj: FoundBrowser) {
    if (!this.ctx.coreData.activeBrowser) {

View on GitHub (pinned to 0d85fdc912)

Solutions

Install a supported browser on the machine (Chrome stable is the most reliable), then restart Cypress so the cache is rebuilt.
On CI/Docker, install Chrome (e.g. apt-get install google-chrome-stable) or use the playwright-webkit / browsers channels Cypress scans, and ensure shared libs are present.
If a browser is installed but not found, set the relevant channel path / ensure it is on PATH, or configure browsers in cypress.config via the bundled-electron fallback.
Inspect coreData.diagnostics.error (shown in the launchpad) for the underlying launcher error — it often names the missing library or permission problem.

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: probe for at least one installed browser before relying on machineBrowsers()
import { detectBrowser } from '@packages/launcher' // or your equivalent

async function hasAnyBrowser(): Promise<boolean> {
  try {
    const list = await browserApi.getBrowsers()
    return list.length > 0
  } catch {
    return false
  }
}

if (!(await hasAnyBrowser())) {
  // surface 'install a browser' guidance to the user; do not proceed
}

Try / catch

try {
  const browsers = await ctx.browser.machineBrowsers()
  // proceed
} catch (e) {
  // coreData.diagnostics.error is already populated by the source's own catch;
  // read it to render the underlying launcher cause in the UI.
  const cause = ctx.coreData.diagnostics.error
  showError('No browser detected', cause?.message ?? e.message)
}

Prevention

Install a supported browser (Chrome stable recommended) on every machine/CI image that runs Cypress.
In Docker/CI images, install browsers and their shared-library dependencies so the launcher does not skip them.
Do not call machineBrowsers() repeatedly expecting fresh results — it caches on coreData; clear the cache explicitly after installing a browser if you need a re-scan.
Always surface coreData.diagnostics.error to the user; it carries the real reason the launcher returned an empty list.

When it happens

Trigger: First call to machineBrowsers() (or any call after a prior failure cleared the cache) when browserApi.getBrowsers() resolves to an empty array. Typically triggered during launchpad startup / browser selection, or when launching a spec.

Common situations: Fresh CI runner or Docker container with no Chrome/Edge/Firefox/WebKit installed; headless server where browsers live outside the scanned paths; Linux missing shared libraries so the launcher detects then skips them; system where only the Cypress-bundled Electron is present but it was filtered out; browser installed under a non-standard channel/PATH.

Related errors

AI-assisted analysis of cypress-io/cypress@0d85fdc912 (2026-08-12). Data as JSON: /api/errors/fe8d15d1f30da57f. Report an issue: GitHub.