Diagnose and fix Puppeteer errors

Start with the operation that failed, not just the last line of the error. A missing browser, a navigation timeout and a detached element need different fixes. This guide shows how to collect useful information and find the right answer in All Puppeteer errors.

Keep the full error

Save the complete message and stack trace, the Puppeteer and browser versions, and the operation that was running. Avoid logging credentials, cookies, page content or URLs with sensitive query parameters.

This example assumes you have created browser and page as shown in the beginner tutorial. Replace the selector with the result your application needs:

try {
    console.log("Browser:", await browser.version());

    await page.waitForSelector("#required-result", {
        timeout: 5000,
    });
} catch (error) {
    console.error(
        "Failed while waiting for the required result",
    );

    console.error(
        error instanceof Error ? error.stack : error,
    );

    throw error;
}

Rethrowing preserves the failure for the caller. Catching an error and returning empty data would make a broken task look successful.

Find where the script failed

• Before the browser starts: check installation and browser paths and sandbox requirements.
• While opening a page: read navigation errors. Check redirects, response status and the condition you are waiting for.
• While waiting for content: use the right wait, rather than increasing every timeout.
• After an iframe or element changes: find the current frame and obtain fresh element handles.
• While clicking or filling a field: check forms and element interaction, including the element type and visibility.
• While handling a request: check request interception and ensure each request is handled once.

On the error reference page, use your browser’s Find command to search for a distinctive part of the message. In entries containing {value}, that placeholder stands for a path, selector or other value from your own error.

Use the error reference

Each entry shows the error message and explains how to fix it. Read the explanation before copying the example: similar messages can come from different operations, and a snippet may assume an existing page, frame or request.

Some errors mean an option or feature is unsupported. Choose a supported option or change the workflow; retries will not add support. Errors involving internal browser state may need a small reproducible example rather than an application-level workaround.

Fix the cause

Change the option, path, selector or waiting condition that caused the failure. Make one relevant change at a time, then run the same operation again. Avoid changing private Puppeteer state, disabling the sandbox or deleting broad cache directories as a general fix.

For a long script, reduce the problem to the smallest sequence that still fails. Remove unrelated steps while keeping the same browser configuration and the page behavior that triggers the error.

Be careful with retries

A timeout does not prove that an action failed. The server might have processed a form while the response was lost. Before repeating a payment, email, account creation or deletion, check the application result or its documented idempotency mechanism.

A fresh frame, a new browser context or a longer timeout cannot undo an action that already succeeded.

For complete workflows and more inline examples, return to the guides.