The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →To debug a Puppeteer script, first identify the exact operation that failed and the execution context involved: your Node.js script, the browser page, the browser process, or the DevTools Protocol connection. Save the full error and stack trace, then use the diagnostic method that exposes evidence at that boundary. Avoid swallowing errors or blindly repeating actions that may have changed application data.
How do I debug Puppeteer scripts?
- Preserve the failure: record the complete error and stack trace, the installed Puppeteer and browser versions, and the operation that was active. Redact credentials, cookies, page contents, and sensitive URL query parameters from logs.
- Locate the failing phase: determine whether the error occurred before browser startup, during navigation, while waiting for content, after an iframe or element changed, during a click or form fill, or while a protocol call was pending.
- Choose a tool for that context: use visible browser output and page events for page behavior, Node’s inspector for orchestration code, browser-process logs for startup or crashes, and protocol diagnostics for pending calls.
- Change one relevant thing: adjust the specific installation setting, executable path, selector, option, or wait condition implicated by the error. Rerun the same operation and reduce the script to the smallest version that still fails.
- Keep failures visible: log useful context and rethrow errors rather than returning empty fallback data that makes a failed task look successful.
Puppeteer’s live debugging guide is served under /next/, so check the documentation for the release you have installed before copying options or examples.
Find the failure boundary before changing code
The final stack-trace line does not always identify the operation that caused the problem. Work backward from the failed or stalled action and note what was running when it happened.
| Failure boundary | First useful check | Evidence it can reveal |
|---|---|---|
| Browser does not start | Check installation scripts, browser cache, executable configuration, sandbox requirements, and platform dependencies. | Whether the failure is setup or environment related rather than an application-script bug. |
| Opening a page | Inspect the navigation error, redirects, response status, and the condition the script awaits. | Whether navigation failed, redirected unexpectedly, or did not reach the state your code expects. |
| Waiting for content | Check whether the wait condition matches the desired page state. | Whether the script is waiting for an event or selector that does not represent readiness for this page. |
| Iframe or element changed | Reacquire the current frame and fresh element handles. | Whether the script is using references made stale by a page or frame change. |
| Clicking or filling | Confirm the target element’s type and visibility. | Whether the target is interactable in the state the script reached. |
| Request interception enabled | Verify every intercepted request is handled once. | Whether an unhandled or multiply handled request is disrupting the flow. |
| Async call hangs or target/session disappears | Collect protocol diagnostics and check whether the relevant page, browser, or target was closed. | Pending-call stacks and evidence that the target or session no longer exists. |
Debug browser-page code separately from Node.js code
See what the browser displays
Run the browser visibly with headless: false. If the automation sequence moves too quickly to inspect, add slowMo; Puppeteer’s current guide uses slowMo: 250 milliseconds as an example, not a universal value.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →#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.
const browser = await puppeteer.launch({ headless: false, slowMo: 250 });Browser-page console output does not automatically appear in Node.js. Forward it with a page event listener:
page.on('console', message => console.log('PAGE:', message.text()));For code evaluated in the page, launch with DevTools enabled and place a debugger statement in the evaluated code. This pauses execution in browser DevTools, where you can inspect page-side variables and the current execution point.
const browser = await puppeteer.launch({ headless: false, devtools: true });
const page = await browser.newPage();
await page.evaluate(() => {
debugger;
// Inspect page-side state here.
});Step through Node.js orchestration
Put a debugger statement in the Node.js script and start it with Node’s inspector paused at startup:
Rank #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.
node --inspect-brk path/to/script.jsIn Chrome or Chromium, open chrome://inspect/#devices, inspect the Node process, and resume execution with F8. This method is documented for Chrome/Chromium. An awaited page action cannot be run directly in the DevTools console because of a Chromium bug; put experiments in the test file instead.
Collect browser-process and protocol diagnostics
When Chrome fails to start or crashes
Set dumpio: true in the launch options to forward browser process output to Node.js standard input and output. These logs can provide browser-side startup or crash clues that the Node exception alone does not show.
const browser = await puppeteer.launch({ dumpio: true });When a protocol call is pending
For lower-level DevTools Protocol diagnostics, run the script with Puppeteer’s debug logging enabled:
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.
NODE_DEBUG="puppeteer:*" node script.jsFor unresolved asynchronous protocol calls, inspect browser.debugInfo.pendingProtocolErrors. The returned errors include stacks showing which code initiated the call. Treat verbose logs as sensitive: review and redact them before sharing because they may include private information.
Fix a Puppeteer browser executable missing or launch error
If failure occurs before a page opens, check the browser installation and cache configuration before rewriting page logic. Puppeteer’s troubleshooting guide explains that modern package managers may block dependency install scripts; if Puppeteer’s install script does not run, the browser may not be downloaded.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Check whether your package manager allowed Puppeteer’s install script to run.
- If the browser is missing, install it manually with
npx puppeteer browsers install, or use the equivalent command for your package manager. - Check the configured executable and cache path. Puppeteer v19.0.0 and later uses
~/.cache/puppeteerby default, according to the troubleshooting guide. - If the home directory or deployment cache is unsuitable, configure
PUPPETEER_CACHE_DIRor a Puppeteer configuration file, then reinstall so the changed configuration takes effect. - Check platform-specific dependencies and permissions before changing launch flags.
Launch failures are not all the same. Windows policies may conflict with Puppeteer’s default disabled extensions; the troubleshooting guide documents enableExtensions: true for that case. Windows sandbox file permissions can also matter. Linux distributions and containers may be missing browser dependencies. The Cloud Run guidance notes that the default Node runtime lacks dependencies needed for Headless Chrome, and that CPU allocation can make work launched after an HTTP response appear very slow. Check the current platform guidance for your environment rather than applying a broad workaround.
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
Puppeteer’s troubleshooting material strongly discourages disabling Chrome’s sandbox and recommends configuring sandboxes. Do not treat --no-sandbox as a routine debugging fix.
Diagnose a Puppeteer navigation timeout or wait that never completes
A timeout tells you the expected condition did not complete within the configured period; by itself it does not identify why. Inspect the navigation error, redirects, response status, and exact wait condition. Then check whether the script is waiting for the page state you actually need, or for a selector or event that never occurs.
- For navigation, identify the specific navigation step and inspect its outcome rather than assuming the whole page is unavailable.
- For a content wait, verify that the selector or condition matches the page state the task requires.
- After frame or DOM changes, get the current frame and reacquire element handles.
- Before increasing timeouts, reduce the script to the smallest sequence that reproduces the same stall.
A timed-out request may still have reached the application. Before retrying a payment, email, account creation, or deletion, check the application result or use its documented idempotency behavior. Do not assume a timeout means the side effect did not happen.
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.
Read the error reference, then make one controlled correction
Use the error’s distinctive wording to locate the corresponding explanation in Puppeteer’s error reference. An error category can arise from different operations, and an example may assume an existing frame, page, or request. Confirm those assumptions against your script before adapting code.
- Keep the original error and a minimal reproduction.
- Change only the option, path, selector, or wait condition connected to the evidence.
- Rerun the same operation under the same relevant browser configuration and page behavior.
- Compare the new result with the original failure before making another change.
This isolates causes more reliably than changing multiple timeouts, launch flags, and selectors at once. The documentation examples and platform guidance can change; confirm them against the installed Puppeteer release and current environment.
Or skip the browser setup
If your goal is to capture a page rather than debug browser automation, ScreenshotNeo offers a one-request screenshot API. It removes cookie and consent banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
For example, this cURL request saves a WebP screenshot of Stripe:
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 options. Learn more at ScreenshotNeo, or sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Which Puppeteer documentation should I use?
Use the documentation matching your installed Puppeteer release; the live debugging guide cited here is under /next/ and may describe options that differ from your version.
Should I use –no-sandbox to fix a launch error?
No. Puppeteer’s troubleshooting guidance strongly discourages disabling Chrome’s sandbox; investigate sandbox configuration and platform requirements instead.
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.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitches
