cypress-io/cypress · error · Error

cy.puppeteer() failed with the following error:\n> ${result.

Error message

cy.puppeteer() failed with the following error:\n> ${result.__error__.message || result.__error__}

What it means

Thrown by the @cypress/puppeteer `cy.puppeteer()` command implementation. The command delegates to a Node-side task `__cypressPuppeteer__` and expects either a result value or an object carrying an `__error__` field. When the task rejects with a structured error, the command re-throws a new Error whose message embeds result.__error__.message (or the raw __error__ if no message). It is a pass-through that surfaces puppeteer-side failures in the Cypress command chain.

Source

Thrown at npm/puppeteer/src/support/index.ts:9

Cypress.Commands.add('puppeteer', (name, ...args) => {
  Cypress.log({
    name: 'puppeteer',
    message: name,
  })

  cy.task('__cypressPuppeteer__', { name, args }, { log: false }).then((result: any) => {
    if (result && result.__error__) {
      throw new Error(`cy.puppeteer() failed with the following error:\n> ${result.__error__.message || result.__error__}`)
    }

    return result
  })
})

View on GitHub (pinned to 0d85fdc912)

Solutions

1. Read the embedded `>` line in the message — it is the underlying puppeteer error and names the real cause.
2. For launch/ECONNREFUSED or 'No usable sandbox' errors, install Chrome deps and pass `--no-sandbox` in the puppeteer launch args configured in your cypress.config.ts task.
3. Ensure `puppeteer` (or `puppeteer-core` + a browser) is installed at the project root and resolvable from the Cypress plugins task.
4. Avoid calling cy.puppeteer after the page navigates away or closes; re-obtain the page reference in the task.

Example fix

// before: launch fails in CI due to missing sandbox
cy.puppeteer('page.goto', 'https://app.local')
// after: configure the task to launch with --no-sandbox
// in setupNodeEvents on('task', '__cypressPuppeteer__'):
//   browser = puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] })

cy.puppeteer('page.title').then((r) => {
  if (r && (r as any).__error__) throw new Error((r as any).__error__.message)
  return r
})

const isPuppeteerError = (r: any): boolean => !!r && typeof r === 'object' && '__error__' in r

cy.task('__cypressPuppeteer__', { name, args }, { log: false }).then((result) => {
  if (result && result.__error__) {
    // surface underlying message, decide retry vs fail
    throw new Error(result.__error__.message || String(result.__error__))
  }
  return result
})

When it happens

Trigger: Calling `cy.puppeteer(name, ...args)` where the Node-side puppeteer task fails (browser launch error, page navigation error, target closed, invalid method name, or an exception inside the task handler). The task returns { __error__: <Error or {message}> } and the browser-side command throws.

Common situations: Puppeteer/Chrome not installed or wrong version; the puppeteer page closed before the action completed; calling a puppeteer method name that does not exist; running headless in CI without required system libs (libX11, libnss); concurrent access from multiple specs corrupting the shared browser instance.

Related errors

• Tests cannot run without a reference to Cypress!
• Missing event for ${event}
• no browsers found in machineBrowsers

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