The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Debug Puppeteer by first locating the failing layer: your script, the page, navigation or network, the DevTools protocol, Chrome itself, or the host environment. Then reproduce the failure with a complete record of versions and launch settings, make the browser visible, and add the kind of logging that matches the symptom; raising every timeout or disabling Chrome’s sandbox can hide the cause or create new risks.
Start by identifying what failed
Puppeteer is a JavaScript library for controlling Chrome or Firefox through the DevTools Protocol or WebDriver BiDi. That means an apparent “Puppeteer error” can originate in several different places. Puppeteer’s own debugging guide notes that there is no single method for debugging every issue because automation touches distinct browser components, including network requests and Web APIs.
Before changing code, write down the operation that was running when it failed and classify the symptom. A launch error happens before a usable browser exists; a navigation timeout occurs while loading or waiting for a page; a selector timeout means the requested element was not found in time; a protocol hang means an asynchronous browser command has not returned; and a page exception is JavaScript executing in the site itself. A process crash, missing system library, or container policy points instead to the host.
| Symptom | Likely layer | First useful evidence |
|---|---|---|
| Chrome does not start or exits immediately | Browser process or host | Full launch error, Chrome stderr, browser installation and dependencies |
goto() does not finish |
Navigation, network, or browser process | Navigation target, request failures, response events, and the chosen wait condition |
waitForSelector() times out |
Page state, frame, or selector logic | Rendered page, current URL, frame state, and whether the element appears conditionally |
| An awaited call never settles | DevTools protocol or browser process | Protocol debug output and pending protocol errors |
| The page renders incorrectly or throws | Page JavaScript, timing, or environment | Console messages, page errors, failed requests, and a visible reproduction |
Preserve a reproducible incident record
Save the complete error and stack trace, not only the final line. Record the exact Puppeteer version, browser version, Node.js version, operating system or container image, launch options, URL, and the operation that failed. Include whether the run was local, in CI, or in a cloud runtime. This is particularly important for version mismatch: Puppeteer releases are tightly paired with browser revisions for DevTools Protocol and WebDriver BiDi compatibility.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Reduce the case to the shortest script and URL that still fail. Keep the original launch flags and timeout values in that reproduction; remove one variable at a time only after you have captured the failure as it occurs.
Make the browser visible and inspect the page
When the issue depends on page state, reproduce it with headless: false. Watching the browser often distinguishes a slow navigation from a wrong URL, a consent overlay, a redirect, a missing element, or a page that never reached the expected state.
- Set
headless: falsein the launch options so Chrome opens on screen. - Put a
debugger;statement immediately before the Puppeteer operation you want to inspect. - Start Node with
--inspect-brk, for examplenode --inspect-brk debug.js. Attach a debugger, then resume execution; the break statement pauses at the chosen line. - For browser inspection, open
chrome://inspect/#devices, choose Inspect for the relevant page, and press F8 to resume when execution is paused. - Inspect the rendered DOM, current frame, console, and network activity at the moment of failure. Compare those observations with what the script expects.
Use the visible run to understand the failure, then verify any fix in the original headless or CI configuration. A local interactive session can expose timing and page-state problems, but it does not recreate every difference in a container or cloud runtime.
Instrument a minimal Puppeteer run
This CommonJS script prints page-side errors, console messages, failed requests, HTTP responses, and browser-process output while preserving thrown errors. Replace the example URL and selector with the target that reproduces the issue. The selector wait is optional; remove it if the failure happens during navigation instead.
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 errorsRank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
const puppeteer = require('puppeteer');
(async () => {
let browser;
try {
browser = await puppeteer.launch({
headless: false,
dumpio: true,
});
browser.on('disconnected', () => {
console.error('Browser disconnected');
});
const page = await browser.newPage();
page.on('console', message => {
console.log(`[page console:${message.type()}] ${message.text()}`);
});
page.on('pageerror', error => {
console.error('[page error]', error);
});
page.on('requestfailed', request => {
console.error('[request failed]', request.url(), request.failure());
});
page.on('response', response => {
if (response.status() >= 400) {
console.error('[HTTP response]', response.status(), response.url());
}
});
const url = 'https://example.com';
console.log('Navigating to', url);
await page.goto(url, { waitUntil: 'domcontentloaded' });
debugger;
await page.waitForSelector('h1', { timeout: 5000 });
console.log('Selector appeared:', await page.title());
} catch (error) {
console.error('Puppeteer operation failed:', error);
console.error(error.stack);
process.exitCode = 1;
} finally {
if (browser) {
await browser.close();
}
}
})();dumpio: true forwards Chrome’s stdout and stderr to the Node process. It is especially useful if Chrome exits before a page can be created. The launch API also documents debuggingPort, pipe, devtools, userDataDir, and waitForInitialPage; change these only when they are relevant to the launch or connection behavior you are investigating. Puppeteer’s current launch API reference specifies a default launch timeout of 30,000 ms.
Trace protocol hangs without guessing
For a command that appears to hang after the browser launched, enable Puppeteer’s internal protocol logging before starting Node:
NODE_DEBUG="puppeteer:*" node debug.jsThe output can be large and may contain sensitive information, so keep it private and avoid publishing unredacted logs. Look for the last protocol activity before the stall and correlate it with the operation in your script. If an asynchronous call never resolves, inspect browser.debugInfo.pendingProtocolErrors. The returned Error objects include stack traces that identify where the pending protocol calls originated, which can connect a low-level hang to the line of application code that issued it.
Fix launch failures by environment
Browser missing or cache inaccessible
Puppeteer normally downloads a compatible browser during installation. If installation scripts were blocked or the expected browser is absent, run npx puppeteer browsers install. If the default cache location cannot be used by the process, set PUPPETEER_CACHE_DIR to a directory the runtime can read and write. In CI, check the install step and the runtime user separately: a browser installed under one account may not be visible to another.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Browser and Puppeteer versions do not match
Check the actual browser binary Puppeteer launched rather than assuming it is the system Chrome. Align Puppeteer with the browser revision it supports. A manually supplied executable or an image that updates Chrome independently can create protocol incompatibilities even when both components start successfully.
Linux sandbox, AppArmor, and missing libraries
A “No usable sandbox!” message can indicate unavailable sandbox support or an AppArmor policy blocking user namespaces. Prefer configuring the host or container correctly. Puppeteer’s troubleshooting guide strongly discourages launching without a sandbox; its documented --no-sandbox workaround is conditional on absolutely trusting the content opened in Chrome, and it changes the security posture of the browser. Do not add it as a routine CI flag.
WSL and minimal CI images may also lack shared libraries Chrome needs. Use the system dependency instructions for the specific environment rather than copying a package list from an unrelated distribution. The needed libraries depend on the image and browser build.
Alpine containers
The troubleshooting guide warns that Chrome does not work on Alpine out of the box and discusses Chromium/Puppeteer compatibility. It also documents a Chromium timeout issue on Alpine 3.20 for a particular scenario, with Alpine 3.19 as the stated workaround for that case. Treat that as environment-specific guidance, not as a general rule that all Alpine builds should be downgraded. Check the browser package, Puppeteer pairing, and exact failure before changing the base image.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Cloud runtime timing
Some cloud execution modes can stop allocating CPU after an HTTP response. The troubleshooting guide identifies this behavior for Cloud Run: background Puppeteer work may then appear extremely slow. Complete the browser work before responding, or configure that platform’s always-on CPU behavior where appropriate. This is distinct from a selector or navigation timeout, so extending Puppeteer’s timer alone will not restore CPU time.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Diagnose navigation and selector timeouts separately
A timeout is evidence that a specific awaited condition did not complete within its configured period; it is not, by itself, evidence that the timeout value is too low. Puppeteer’s Page API documents that a selector wait throws if the selector does not appear before the timeout.
- For navigation: confirm the URL and redirects, inspect request failures and response statuses, and decide whether the chosen navigation wait condition matches the page. A page that keeps connections open may not suit a wait condition that expects network activity to become idle.
- For a selector: inspect the page at timeout, verify the selector against the rendered DOM, and check whether the element is inside another frame or appears only after an interaction or conditional render.
- For detached elements: locate the element again after navigation or rerender rather than assuming a prior handle still points to live page content.
- For inconsistent timing: wait for the specific state the next action requires, rather than inserting a large fixed delay. Use a delay only when investigating a reproducible timing issue, not as a substitute for identifying the state.
Increase a timeout only when the operation is correct and the observed environment legitimately needs more time. Apply the adjustment to the specific wait that is too short; a global increase can make broken conditions take longer to diagnose.
Keep local, CI, and production behavior comparable
When a script works locally but fails in CI, compare the inputs before changing the test: Puppeteer and browser versions, Node version, OS or image, install user and cache directory, launch arguments, available libraries, and runtime permissions. Then compare the evidence from the browser and network logs. A headless local run on the same image can narrow the gap between a visible desktop session and CI.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Separate reliability from security. Repeated crashes before page creation point toward process or host diagnostics such as dumpio; failures only on certain sites can involve navigation, page state, or network conditions; and a sandbox workaround may make startup appear successful while reducing isolation. Preserve the original error, make one controlled change, and confirm that the same minimized case succeeds under the deployment configuration.
Or skip the browser setup
If the task is to obtain a page screenshot rather than debug a custom browser workflow, ScreenshotNeo offers a screenshot API and MCP server. Its API uses one GET request; it can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture, with each cleanup step switchable. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; responses identify the page verdict and billing status in headers. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf.
For example, save a WebP screenshot of the target URL with cURL (replace the URL with the page you need):
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. A free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots. Sign up for the free plan to try it.
Free tools Windows power users keep installed
One-click scans. No signup required.
Frequently Asked Questions
Can Puppeteer automate Firefox as well as Chrome?
Yes. Puppeteer’s official documentation describes control of Chrome or Firefox through the DevTools Protocol or WebDriver BiDi. Browser-specific behavior and version compatibility still need to be considered when reproducing a failure.
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.
