Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsMost Puppeteer failures can be narrowed down by identifying the stage that failed: browser discovery, Chrome startup, navigation, element interaction, or deployment. Record your Puppeteer version, browser version, operating system or container image, and the exact error before changing settings; that makes it easier to distinguish a code problem from a browser, permission, or runtime problem.
Start with the failing stage
Read the error in context: did Puppeteer fail to locate Chrome, fail to start it, start it but fail to navigate, or reach the page and then time out waiting for an element? Those stages have different likely causes. Compare the failing stage with the operating system or container, file permissions, Puppeteer and browser versions, security impact of any proposed launch change, the page condition a timeout is meant to wait for, and deployment caching or runtime behavior.
As an Amazon Associate I earn from qualifying purchases.
- Capture the exact error and the command or code path that triggered it.
- Record the installed Puppeteer version, Chrome/Chromium version, OS or container image, and process user.
- Change one setting at a time and keep the original error output for comparison.
The official Puppeteer troubleshooting guide has environment-specific notes; its recommendations are not interchangeable across all Linux distributions, containers, and cloud runtimes.
Why can’t Puppeteer find its browser?
First check whether installation downloaded a browser and where Puppeteer expects its cache. Since Puppeteer v19.0.0, the default download cache is ~/.cache/puppeteer. Set PUPPETEER_CACHE_DIR to relocate it if your build or runtime cannot use that path.
#1 Best Overall
- Inspect the install log and confirm the browser download completed.
- Check that the runtime process can read the configured cache and execute the browser binary.
- If your build reuses
node_modulesor installs in one environment and runs in another, make sure the browser cache is present in the runtime image. The troubleshooting guide gives App Engine and Cloud Functions examples where placing the cache insidenode_modulescan help with executable discovery.
You can set executablePath to use another browser binary, but Puppeteer documents that it is only guaranteed to work with its bundled browser. See the LaunchOptions API before pointing to a separately installed Chrome or Chromium.
Why does Chrome fail to launch?
Check Linux libraries and permissions
A browser launch failure is not automatically a Puppeteer code bug. On Linux, missing shared libraries, an executable that is absent or unreadable, filesystem permissions, sandbox setup, and unwritable profile or cache paths can all stop Chrome before Puppeteer connects. The troubleshooting guide suggests checking unresolved browser dependencies with ldd chrome | grep not, then installing the dependencies appropriate to the target distribution.
- Confirm the configured browser executable exists and is executable by the process user.
- Check that the browser user can read required libraries and write to profile and cache locations.
- Use the error output to distinguish a missing library from a sandbox or path-permission failure.
Check Windows policies and version context
On Windows, Chrome policies can conflict with Puppeteer’s default extension behavior. Puppeteer also documents a permissions workaround for sandbox access errors with downloaded Chrome in older Puppeteer versions or installations that still encounter the issue. Check the version and policy context in the official guide rather than applying a workaround as a universal Windows fix.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Collect launch output before raising the timeout
The current LaunchOptions reference lists a 30,000 ms (30-second) default launch timeout. It also provides timeout to configure the limit and dumpio to forward browser stdout and stderr to the process. Use dumpio to collect Chrome’s startup output before simply increasing the launch timeout; a longer wait does not fix a missing library or denied write.
How should you handle Linux sandbox errors?
If Chrome reports No usable sandbox!, investigate the host’s sandbox configuration. Chrome uses multiple sandboxing layers, and disabling them trades away a security boundary. The Puppeteer troubleshooting documentation states: “Running without a sandbox is strongly discouraged.”
Ubuntu 23.10 and newer may have an AppArmor profile that blocks user namespaces for Puppeteer-downloaded Chrome for Testing binaries. In that case, consult the environment-specific workaround linked from Puppeteer’s troubleshooting documentation and the linked Chromium sandbox documentation. Do not assume a sandbox-disabling launch flag is the right fix for every host.
Why does Chrome crash at startup in a container?
Chrome writes profile, configuration, and cache files when it starts. In a read-only or restricted container, provide writable locations for these files, or mount writable volumes owned by the browser process user. A possible symptom of unwritable paths is chrome_crashpad_handler: --database is required.
Recommended Free Tools
- Identify which paths the browser process can write to in the running container.
- Provide writable config/cache directories and a writable user-data directory, or mount writable volumes with suitable ownership.
- Re-run with browser output enabled and check whether startup proceeds past the original filesystem error.
Do not assume the host filesystem’s permissions carry over into the container: inspect them as the same user that launches Puppeteer.
What should you know about Alpine and browser compatibility?
The Puppeteer troubleshooting guide says Chrome does not support Alpine out of the box and requires compatible system dependencies. It also records timeout issues with the Chromium version current for Alpine 3.20 when that guidance was written, and discusses matching Chromium with a supported Puppeteer version. Treat that as version-specific guidance, not a permanent rule for every Alpine image. Check the current Puppeteer compatibility and platform notes for the exact browser and image versions you deploy.
Why do navigation and selector waits time out?
Identify the wait that actually expired
A timeout means a particular operation did not finish within its configured limit. It does not by itself show that the page is broken. Establish whether the timeout came from browser launch, navigation, a selector wait, or an interaction, then verify that the condition being awaited can occur.
The current wait options reference lists 30,000 ms (30 seconds) as the default wait timeout. It also describes waitUntil, which selects the lifecycle event that resolves a navigation wait; the listed default is load. Choosing a different lifecycle event changes when the wait resolves. It does not guarantee that every application-specific element or asynchronous update is ready.
Prefer locators for element interactions
Puppeteer’s current page interactions guide recommends locators for selecting and interacting with elements. Locators wait for the element and relevant action preconditions, which is often more reliable than selecting an element too early and immediately acting on it.
If an interaction still times out, check that the selector is valid in the current page or frame, that the element appears after any asynchronous update, and that the required visibility or enabled state can actually occur. A selector for an element inside a different frame or a state the application never reaches will not be fixed by a longer timeout.
Use waitForSelector when lower-level behavior is needed
waitForSelector remains available when you need its lower-level behavior. Its documented timeout defaults to 30,000 ms and can be configured per call or through page defaults. The returned element handle should be disposed when appropriate so it does not remain unnecessarily retained.
How do cloud deployment and process behavior affect Puppeteer?
Puppeteer’s troubleshooting guide includes examples for App Engine, Cloud Functions, Cloud Run, Heroku, and AWS Lambda, but the remedy depends on the provider’s runtime and configuration. For example, the guide says Cloud Run’s default Node.js runtime does not include the system packages needed for Headless Chrome, so deployment needs its own Dockerfile and dependencies. It also notes that CPU allocation after an HTTP response can affect work started in the background.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →- Verify the current provider runtime, installed system packages, writable paths, and browser cache in the deployed image.
- For work continuing after an HTTP response, check the provider’s CPU allocation behavior and ensure the process model supports that work.
- If zombie Chrome processes persist in Docker, check whether process management such as
dumb-initis relevant to the container setup; it is an operational tip, not a universal requirement.
Because provider settings and runtime images change, use the platform sections in the official Puppeteer deployment troubleshooting guide as a starting point and confirm the current provider configuration.
Best Value
Or skip the browser setup
If the goal is simply to capture a website rather than debug a local Chrome installation, ScreenshotNeo offers a website screenshot API and MCP server. One GET request returns a screenshot or PDF; its API and parameters are documented at ScreenshotNeo docs.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Free tools Windows power users keep installed
One-click scans. No signup required.
Sign up free for 1,000 screenshots a month, with no card required.
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.
