What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Puppeteer errors are easiest to fix when you identify which stage failed: browser installation, Chrome launch, page navigation, or an interaction such as waiting for a selector. Start by checking the exact Puppeteer/browser pairing and runtime environment; a timeout or launch error is a symptom, not a diagnosis.
First, identify the failure stage
Use the error message and the operation that produced it to narrow the search before changing launch flags or increasing timeouts.
As an Amazon Associate I earn from qualifying purchases.
| Stage | Typical symptom | First check |
|---|---|---|
| Install | Could not find expected browser locally |
Whether Puppeteer downloaded its browser and whether install-time and runtime cache paths match. |
| Launch | Failed to launch chrome, missing shared libraries, sandbox errors, or crashpad database errors |
Browser/Puppeteer version, Linux dependencies, sandbox configuration, and writable directories. |
| Navigate | page.goto() throws, or navigation returns an unexpected page |
URL validity, network reachability, SSL, response status, and browser warning pages. |
| Interact | TimeoutError from a selector wait or another operation |
Selector correctness, page state, and whether the expected element can appear. |
There is no substantiated public incidence data here that ranks these errors by frequency. Treat the table as a diagnostic map, not a statistical ranking.
Fix “Could not find expected browser locally”
Puppeteer needs the browser build associated with its release, installed where that project’s runtime can find it. Starting with Puppeteer v19, the default browser cache is ~/.cache/puppeteer, based on the home directory. A different user, container layer, or HOME at runtime can therefore make an installed browser appear absent.
#1 Best Overall
- Check the project’s exact Puppeteer version and whether its installation completed successfully.
- Confirm that the process running Puppeteer uses the same home directory and cache configuration as the install process.
- If the package manager blocked install scripts, install the browser explicitly with
npx puppeteer browsers install. Puppeteer’s troubleshooting guide also documents the corresponding Yarn, pnpm, and Bun routes. - If you configure a custom cache directory, reinstall the browser after changing that setting so the install uses the new location.
See the Puppeteer troubleshooting guide for the current manual-install commands and cache configuration details.
Fix Chrome launch failures on Linux
Check missing system libraries
A Chrome executable can exist and still fail because shared libraries required by that distribution are missing. Inspect the executable’s dependencies; Puppeteer’s troubleshooting guide suggests checking ldd chrome for missing libraries. Install the dependencies appropriate to the operating system and image you actually deploy. Use the current platform dependency lists rather than copying an old package list into a new container.
Puppeteer’s system requirements page describes supported operating systems and links to platform-specific dependency information. It currently lists Node.js 22.12 or later; check that page when selecting a runtime because requirements can change.
Rank #2
Diagnose sandbox errors without disabling protections by default
For No usable sandbox!, investigate the host’s sandbox setup and distribution configuration. Puppeteer strongly discourages running Chrome without its sandbox. Its guide describes --no-sandbox only for content the operator absolutely trusts, not as a routine fix for a broken deployment.
On Ubuntu 23.10 and later, AppArmor restrictions on user namespaces may affect downloaded Chrome for Testing. Check whether that specific host restriction applies before changing launch arguments.
Align Puppeteer with its browser
Puppeteer releases are deliberately paired with specific browser releases because the automation protocols can change. The Puppeteer FAQ explains: “Every Puppeteer release is tightly bundled with a specific browser release to ensure compatibility with the implementation of the underlying protocols, the Chrome DevTools Protocol and WebDriver BiDi.” Check the supported browsers table for your project’s precise Puppeteer version instead of assuming the machine’s system Chrome is compatible.
Starting with Puppeteer v20, its Chrome path uses Chrome for Testing; older releases used Chromium. If you changed Puppeteer, Chrome, or a system package independently, restore the documented pairing or deliberately configure a supported executable. Do not assume that “latest Chrome” is the right match.
Fix crashpad errors in read-only containers
An error such as chrome_crashpad_handler: --database is required can indicate that Chrome cannot create the profile, configuration, or cache files it needs at startup. A read-only container filesystem does not remove those write requirements.
- Provide writable locations for XDG configuration and cache, such as writable paths under
/tmp. - Set an explicit writable Puppeteer
userDataDirfor Chrome’s profile. - Verify that the process user owns or can write to the mounted directories.
The Puppeteer deployment troubleshooting guidance includes writable-path approaches. Apply them to the user and filesystem layout in your own container rather than assuming a path is writable merely because it exists.
Diagnose TimeoutError and navigation failures
Do not treat every timeout as a slow page
Puppeteer’s TimeoutError class means an operation was terminated after its timeout elapsed; it does not identify the root cause. For page.waitForSelector(), first confirm that the selector is correct, the relevant page has loaded into the expected state, and the element is actually expected to appear. Raising the timeout cannot fix a selector that never matches or a flow that never reaches that state.
For a timeout from puppeteer.launch(), investigate browser installation, executable compatibility, system dependencies, and the host/container environment rather than adjusting a page wait.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsCheck the specific reasons page.goto() can fail
The Frame.goto() API documentation lists possible causes including an invalid URL, SSL errors, an expired navigation timeout, an unreachable server, failure of the main resource, or rejection by URL allowlist/blocklist rules.
Best Value
- Used Book in Good Condition
- Confirm the URL is valid and reachable from the machine running Chrome, not just from your workstation.
- Check certificate and SSL behavior, proxy/network access, and any URL restrictions configured by the application.
- Inspect the navigation response status. In headless shell, a valid HTTP response such as 404 or 500 does not by itself make
goto()throw; the page can load with an HTTP error status. - Remember the special cases:
about:blankand same-URL hash changes have success behavior documented by Puppeteer.
Verify ERR_BLOCKED_BY_CLIENT before applying a workaround
Puppeteer documents a Chrome for Testing HTTPS-warning behavior that can make remote HTTP navigation return net::ERR_BLOCKED_BY_CLIENT. In the described case, Chrome displays a warning page; the guide documents clicking through that interstitial or a launch argument that disables the feature. Local HTTP hosts do not trigger the warning in that case. Verify that the page is actually this warning interstitial before using the workaround; the same error text should not be assumed to have one universal cause.
Collect useful diagnostics instead of guessing
- Set
dumpio: truein the Puppeteer launch options to forward browser-process output to Node’s standard streams. - If an asynchronous call remains unresolved, use the protocol logging approach described in Puppeteer’s debugging guide, including
NODE_DEBUG. - Inspect
browser.debugInfo.pendingProtocolErrorswhen investigating pending protocol errors. - Review logs before sharing them: browser and protocol output can contain request or page details, so treat it as potentially sensitive.
Or skip the browser setup
If your goal is to obtain a page screenshot rather than to debug a Puppeteer deployment, ScreenshotNeo provides a screenshot API and MCP server. A single GET request can return a PNG, JPEG, WebP, or PDF. Its clean-shot steps can accept cookie/consent banners and remove 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf.
Example cURL request (replace the URL with the page to capture):
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request parameters and response details. One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo and start with 1,000 free screenshots a month, no card required.
Frequently Asked Questions
Does a 404 response mean Puppeteer navigation failed?
Not necessarily. In headless shell, a valid HTTP response such as 404 or 500 does not itself make goto() throw; inspect the response status.
Should I always add --no-sandbox to fix Chrome launch errors?
No. Puppeteer strongly discourages disabling the sandbox; diagnose the host’s sandbox configuration first.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
