What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Debug Puppeteer by first identifying whether the failure is in your Node.js code, JavaScript running in the page, or the browser/runtime. Then choose the least intrusive diagnostic that exposes evidence from that layer: show the browser, forward page logs, pause in a debugger, or inspect protocol and browser-process output. For common launch failures, verify the installed browser and launch configuration before changing sandbox or permission settings; for timeouts, check the selector and the state Puppeteer is waiting for.
Start by identifying which layer is failing
Puppeteer crosses several boundaries: your Node.js program sends commands, the page runs its own JavaScript, and a separate browser process renders and operates the site. A symptom such as a hang or failed click does not by itself reveal which layer is responsible. The Puppeteer Debugging guide notes that there is no single debugging method for every issue because Puppeteer touches many browser components, including network requests and Web APIs: Puppeteer Debugging guide.
- Node.js layer: your script’s control flow, exception handling, or awaited operation may be wrong.
- Page layer: the site may not have rendered the expected content, or its JavaScript may have failed.
- Browser/runtime layer: Chrome may fail to launch, crash, lack permissions or dependencies, or be incompatible with a custom executable.
- Protocol layer: a command sent between Puppeteer and the browser may be stalled or rejected.
Reproduce the smallest failing case you can, record the exact error and operation that produced it, and inspect one layer at a time. Avoid enabling every logging option at once: some diagnostics add noise, slow reproduction, or expose sensitive page data.
Recommended Free Tools
Make a failure visible before adding more logging
Open a visible browser and slow down actions
For a quick visual check, launch with headless: false. You can also set slowMo to insert a delay between Puppeteer operations, making clicks and navigation easier to observe. These are useful first checks when a script appears to click the wrong thing, run too early, or stall unexpectedly.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
const browser = await puppeteer.launch({
headless: false,
slowMo: 100,
});Use this as a diagnostic, not necessarily as the final deployment configuration. A visible browser changes the environment and may be unavailable in a headless server or container.
Forward page console messages to Node.js
Page-side console.log, console.warn, and console.error output does not automatically appear in the Node.js process. Attach a listener before navigating so you do not miss early messages:
page.on('console', message => {
console.log(`[page:${message.type()}] ${message.text()}`);
});
page.on('pageerror', error => {
console.error('[page error]', error);
});The first listener relays browser-console messages; the second reports uncaught exceptions from page JavaScript. If the page logs an error but your Node process does not, this bridge is often the missing observability step.
Pause execution in page or Node.js code
For browser-side JavaScript, launch with DevTools enabled and put a debugger statement at the point where execution should pause. For server-side code, start Node with its inspector, such as node --inspect-brk script.js, use a visible browser to observe the page, and put a debugger statement in the relevant Node.js path. The browser debugger and Node inspector investigate different runtimes; a breakpoint in one will not pause the other.
Inspect protocol traffic or browser-process output
If ordinary logs do not explain a stalled operation, Puppeteer’s debugging guidance documents NODE_DEBUG="puppeteer:*" for DevTools protocol traffic and browser.debugInfo.pendingProtocolErrors for pending protocol-call errors and their stack traces. Protocol logs can contain sensitive information, so restrict access, avoid publishing raw logs, and redact secrets before sharing them.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
When Chrome crashes or fails during startup, set dumpio: true in launch options to forward the browser process’s stdout and stderr to the Node.js process:
const browser = await puppeteer.launch({
dumpio: true,
});This can reveal browser startup or runtime messages that Puppeteer’s own exception does not include. Enable it for a focused reproduction and turn it off when it is no longer useful.
Fix browser launch and environment failures
Confirm which browser Puppeteer is trying to start
The LaunchOptions reference surfaced as Puppeteer 25.12.0 documents Chrome as the default browser, headless: true as the default headless setting, and a 30,000-millisecond default browser startup timeout. Setting timeout: 0 disables that launch timeout. Check the actual options your script passes, because an explicit browser choice, channel, executable path, or timeout can change the behavior. See the LaunchOptions reference.
A custom system browser is not guaranteed to work with Puppeteer. If launch fails, first test with the browser installation intended for your Puppeteer setup; then treat a custom executablePath or channel as a compatibility variable. Do not assume that any installed Chrome or Chromium binary is interchangeable.
Check whether the browser is installed in the expected cache
Puppeteer’s troubleshooting guide says that starting with Puppeteer v19, downloaded browsers are stored under ~/.cache/puppeteer by default. The PUPPETEER_CACHE_DIR environment variable can change that location. Confirm the account running Node.js can read the configured cache and that the browser download happened for that environment; a browser installed under a developer account may not exist for a service or container user. See the Puppeteer troubleshooting guide.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Investigate permissions, sandboxing, profiles, and dependencies
The troubleshooting page is the official /next/ guide and says its advice relies largely on community contributions. Platform-specific requirements can change with browser, operating-system, and deployment releases, so verify them against the environment you actually run.
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 →- Windows: check whether Chrome policy or permissions on the downloaded browser prevent startup.
- Linux: investigate sandbox configuration and possible AppArmor restrictions.
- User data: make sure the browser’s user-data directory is writable by the process account.
- System libraries: verify the dependencies required by the browser image, especially in minimal or Alpine-based environments.
Puppeteer’s troubleshooting guidance strongly discourages using --no-sandbox. Rather than reflexively disabling the sandbox, diagnose why the sandbox cannot operate and configure the environment appropriately. Disabling a browser security boundary is not a general-purpose launch fix.
Distinguish a slow startup from a failed startup
If startup is simply slower than the configured limit, the launch timeout can be adjusted through launch options. But increasing it will not repair a missing executable, denied permissions, incompatible browser, unavailable system dependency, or sandbox restriction. Capture the browser-process output with dumpio: true and verify the installation and environment before treating a longer timeout as the solution.
Resolve selector and interaction timeouts
Understand what timed out
Puppeteer throws a TimeoutError when an operation such as page.waitForSelector or puppeteer.launch reaches its time limit. The error means the awaited operation did not complete within the configured window; it does not identify the underlying cause by itself. See the TimeoutError reference (surfaced as Puppeteer 25.11.0).
For a selector wait, verify that the selector matches the live page and that the relevant content has had a chance to load. The waitForSelector API waits for a selector to appear and can distinguish element presence from visibility through its options; its timeout can also be changed. See the waitForSelector API reference.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
const element = await page.waitForSelector('.result', {
visible: true,
timeout: 10_000,
});Use a visibility condition when the next action requires an element the user could see. Merely finding a matching node is not proof that it is visible or ready for the intended interaction.
Prefer locators for user-like interactions
Puppeteer recommends locators for interactions. A locator waits for an element to be present and in the right state for the requested action. If it times out, either the element was not found or its action preconditions were not met in time. Check the selector and expected action state rather than increasing the timeout automatically. The Page interactions guide describes waitForSelector as a lower-level API.
For example, a locator can express the intended action directly:
await page.locator('button[type="submit"]').click();If the page uses frames or shadow DOM, confirm that your selector strategy targets the correct context. A selector valid in the main document may not address content inside a different frame or shadow root.
Dispose element handles when using the lower-level flow
waitForSelector returns an element handle when it finds a match. If you keep using that lower-level API, dispose of handles when finished so they do not linger longer than needed:
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
const handle = await page.waitForSelector('.result', { visible: true });
try {
// Inspect or operate on the matched element.
} finally {
await handle?.dispose();
}Use a locator when its automatic waiting suits the interaction; use an element handle when you need the lower-level control, and account for its cleanup.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A practical troubleshooting sequence
- Capture the exact failure: note the operation, selector or URL involved, full error text, and whether the failure is repeatable.
- Classify the layer: decide whether the evidence points to Node.js control flow, page JavaScript, browser startup/runtime, or a protocol call.
- Observe the page: reproduce with
headless: falseand, if needed,slowMo. - Bridge page output: attach
consoleandpageerrorlisteners before navigation. - Pause at the failure: use DevTools for page JavaScript or Node’s
--inspect-brkfor server code. - Escalate diagnostics selectively: use protocol debugging for stalled commands and
dumpio: truefor browser-process failures, protecting logs that may include sensitive data. - For launch errors: verify browser installation and cache, selected executable, permissions, sandbox, writable profile path, and system dependencies.
- For selector errors: verify the live selector, frame or shadow-root context, and whether the required state is presence, visibility, or action readiness.
Or skip the browser setup
If the goal is to capture a page rather than debug a Puppeteer workflow, ScreenshotNeo provides a screenshot API and MCP server. Its API returns an image or PDF from one GET request; cookie banners, popups, and chat widgets are removed before capture. Bot checks, blank pages, and failed loads are not billed, and responses include page-verdict and billing headers. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
cURL example, using Stripe as the target URL:
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 documentation for API details. Sign up free for 1,000 screenshots a month, with no card required.
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 errorsFAQ
Why do page console messages not appear in my Node.js terminal?
Page console output runs in the browser context and does not automatically flow to Node.js. Add a page console event listener and relay the message, as shown above.
Does increasing a timeout fix a Puppeteer timeout?
Only when the operation is succeeding but needs more time. If the selector is wrong, the browser cannot launch, or an interaction’s readiness conditions are not met, a longer wait only delays the same failure.
Should I use --no-sandbox to fix Chrome launch errors?
No as a reflexive fix. Puppeteer’s troubleshooting guide strongly discourages it; investigate sandbox configuration and the deployment environment 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.
