{"record":{"id":"c4f99cad1b822ec4","repo":"cypress-io/cypress","slug":"cy-puppeteer-failed-with-the-following-error-n","errorCode":null,"errorMessage":"cy.puppeteer() failed with the following error:\\n> ${result.__error__.message || result.__error__}","messagePattern":"cy\\.puppeteer\\(\\) failed with the following error:\\\\n> (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"npm/puppeteer/src/support/index.ts","lineNumber":9,"sourceCode":"Cypress.Commands.add('puppeteer', (name, ...args) => {\n  Cypress.log({\n    name: 'puppeteer',\n    message: name,\n  })\n\n  cy.task('__cypressPuppeteer__', { name, args }, { log: false }).then((result: any) => {\n    if (result && result.__error__) {\n      throw new Error(`cy.puppeteer() failed with the following error:\\n> ${result.__error__.message || result.__error__}`)\n    }\n\n    return result\n  })\n})\n","sourceCodeStart":1,"sourceCodeEnd":15,"githubUrl":"https://github.com/cypress-io/cypress/blob/0d85fdc91230885bca0a91df278312800a48b727/npm/puppeteer/src/support/index.ts#L1-L15","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the embedded `>` line in the message — it is the underlying puppeteer error and names the real cause.","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.","Ensure `puppeteer` (or `puppeteer-core` + a browser) is installed at the project root and resolvable from the Cypress plugins task.","Avoid calling cy.puppeteer after the page navigates away or closes; re-obtain the page reference in the task."],"exampleFix":"// before: launch fails in CI due to missing sandbox\ncy.puppeteer('page.goto', 'https://app.local')\n// after: configure the task to launch with --no-sandbox\n// in setupNodeEvents on('task', '__cypressPuppeteer__'):\n//   browser = puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] })","handlingStrategy":"try-catch","validationCode":"cy.puppeteer('page.title').then((r) => {\n  if (r && (r as any).__error__) throw new Error((r as any).__error__.message)\n  return r\n})","typeGuard":"const isPuppeteerError = (r: any): boolean => !!r && typeof r === 'object' && '__error__' in r","tryCatchPattern":"cy.task('__cypressPuppeteer__', { name, args }, { log: false }).then((result) => {\n  if (result && result.__error__) {\n    // surface underlying message, decide retry vs fail\n    throw new Error(result.__error__.message || String(result.__error__))\n  }\n  return result\n})","preventionTips":["Ensure puppeteer/chromium and required OS libs are installed in CI.","Pass --no-sandbox in the task's launch args for CI environments.","Avoid invoking puppeteer methods after the page closes; obtain a fresh reference."],"tags":["puppeteer","task","browser","pass-through-error"],"backgroundTag":null,"analyzedSha":"0d85fdc91230885bca0a91df278312800a48b727","analyzedAt":"2026-08-12T16:24:28.056Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}