Recommended Free Tools
Fix a Puppeteer timeout by identifying which operation failed: browser startup, navigation, a page-condition wait such as waitForSelector(), or management of an already running browser. Each has a different control. Raising a limit can allow a genuinely slow operation more time, but it will not fix a missing browser, a wrong selector, or a wait for the wrong event.
Identify the operation that timed out
Start with the exact failing call and timeout message, not a blanket increase to every timeout. Record the stack location, Puppeteer and browser versions, and whether the browser was launched locally or connected remotely. The LaunchOptions reference, Page API, and browser-management guide describe separate controls and lifecycle behavior.
As an Amazon Associate I earn from qualifying purchases.
puppeteer.launch()fails: investigate browser startup and environment setup.page.goto()or another navigation call fails: check the URL, server response, redirects, and navigation condition.waitForSelector()or another page wait fails: check the condition, selector, frame, and when the application becomes ready.- A remote browser is involved: check connection and who owns the browser’s lifecycle.
Choose the right timeout control
Puppeteer documents a 30,000-millisecond default for launch and page waits in the cited API references. Defaults and available options can depend on the installed version, so verify them against the documentation for that version.
| What is waiting | Control | Scope |
|---|---|---|
| Browser process startup | puppeteer.launch({timeout}) |
Launch only. The LaunchOptions reference specifies a 30,000 ms default; 0 disables the timeout. |
| Navigation | page.setDefaultNavigationTimeout(ms) |
Navigation methods including goBack, goForward, goto, reload, setContent, and waitForNavigation. |
| General page waits | page.setDefaultTimeout(ms) |
Page-level default for general waits, including selector waits. |
| One specific wait | The method’s timeout option |
That operation only. Wait options use milliseconds; 0 disables the timeout. |
| Cancel a wait | signal: AbortSignal |
Supported by documented wait options, including selector waits. |
These distinctions are documented in the Page API and LaunchOptions.
#1 Best Overall
Fix launch timeouts
A launch timeout means Puppeteer did not start the browser within the allotted time. Check that the expected browser is installed and runnable in the deployment environment, including required runtime libraries and permissions. Increasing a launch timeout is reasonable only when startup is slow but otherwise succeeds.
Puppeteer’s configuration guide notes that package managers that block install scripts can prevent automatic browser download. The documented manual remedy is:
npx puppeteer browsers installUse the launch option only when the environment is correct and startup needs longer:
Free tools Windows power users keep installed
One-click scans. No signup required.
const browser = await puppeteer.launch({ timeout: 60_000 });This changes the startup allowance to 60 seconds; it does not install a missing browser or resolve a permissions or runtime-library problem. Check the launch-options documentation for the behavior supported by your installed Puppeteer version.
Fix navigation timeouts
Navigation waits can fail because the response is slow, a redirect or server behavior differs from expectations, or the script waits for a lifecycle event the page does not reach promptly. Puppeteer supports navigation lifecycle conditions such as domcontentloaded, load, and networkidle. Pick the condition that represents the task’s success rather than waiting for the strongest condition by default.
For example, if the task needs the initial DOM rather than every resource or background request to finish, use an appropriate navigation option and, if warranted, a longer per-call timeout:
await page.goto('https://example.com', {
waitUntil: 'domcontentloaded',
timeout: 45_000,
});Alternatively, set a page-wide navigation policy when that longer allowance is appropriate for all navigation methods on the page:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11page.setDefaultNavigationTimeout(45_000);
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });The navigation methods affected by this setting are listed in the Page API. A network-idle wait may remain unsatisfied if a page continues making requests even though the specific content needed is ready; prefer a selector or application-specific condition when that is the real success signal.
Fix selector and page-condition timeouts
waitForSelector() waits for the requested selector condition; it does not establish that navigation is complete. By default, it waits for the selector to be present. The visible and hidden options change the condition. The documented default is 30,000 milliseconds, and timeout: 0 disables it. An AbortSignal can cancel the wait. See the Page API.
await page.waitForSelector('[data-testid="results"]', {
visible: true,
timeout: 20_000,
});If it times out, check that the selector is correct, that the element is in the frame being queried, and whether it needs to be present, visible, or hidden. If a client-side render or API response determines readiness, wait for a signal tied to that outcome rather than assuming navigation completion means the content is ready. Puppeteer also documents waits for requests, responses, navigation, network-idle, and function conditions in the Page API.
Avoid the click-and-navigation race
If clicking an element triggers navigation, begin waiting for navigation before the click can trigger it. Awaiting the click and then attaching a navigation wait can miss the event. Puppeteer’s Page API documents this concurrent pattern:
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 →const [response] = await Promise.all([
page.waitForNavigation({ waitUntil: 'domcontentloaded' }),
page.click('a.next'),
]);Choose a waitUntil condition that matches the page and task. The navigation response can be null for some navigation types, so do not treat a missing response object alone as proof the wait failed. See Page API.
Rank #4
Manage a connected browser without closing the wrong thing
When connecting to a browser managed elsewhere, distinguish detaching Puppeteer from shutting down the browser. The official browser-management guide documents browser.disconnect() as detaching Puppeteer without closing the browser or its pages; browser.close() gracefully closes the browser.
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/...',
});
// End this Puppeteer connection but leave the externally managed browser running.
browser.disconnect();Use browser.close() only when this script owns the browser process and should shut it down. For a remotely managed browser, confirm lifecycle ownership before choosing either action.
Use bounded waits and cancellation
A timeout of 0 removes Puppeteer’s limit for that wait. Use it only when an outer deadline, cancellation mechanism, or other control still bounds the job; otherwise a stuck operation can run indefinitely. Prefer a per-operation timeout for an exceptional slow step and a page default only when the broader policy is intentional.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Where supported by the wait, an abort signal provides another way to cancel:
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 30_000);
try {
await page.waitForSelector('[data-testid="results"]', {
signal: controller.signal,
timeout: 0,
});
} finally {
clearTimeout(timer);
}Use this pattern only with Puppeteer versions whose wait options support signal; consult the installed version’s API reference. The external timer is the bound in this example, because the wait’s own timeout is disabled.
Troubleshoot by symptom
- Launch fails before a page exists: verify browser installation, executable availability, runtime libraries, and permissions. If install scripts were blocked, use the documented
npx puppeteer browsers installremedy. - Navigation times out although the site appears usable: review the chosen
waitUntilcondition. A page with continuing background requests may not become network-idle; wait for the content the task actually needs. - A selector wait times out: check spelling, frame, presence versus visibility, and whether application rendering has completed. A selector wait is not a navigation wait.
- Click-triggered navigation is missed: create the navigation wait and click together with
Promise.all(). - A connected browser unexpectedly stops or stays open: check whether the script should detach with
disconnect()or close the browser withclose(). - Increasing the timeout changes nothing: verify that the failing operation uses that timeout scope. A launch timeout does not change selector waits, and a navigation default does not correct a bad selector.
Or skip the browser setup
If your task is to retrieve a website screenshot rather than run a browser automation workflow, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents and other MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does a Puppeteer selector timeout mean the page failed to load?
No. It means the requested selector condition was not satisfied before that wait expired; navigation and selector waits are separate.
Does Puppeteer’s 30-second default apply to every timeout?
No. Launch, navigation, and general page waits have different controls and scopes. Check the API reference for your installed version.
Can I disable a Puppeteer timeout safely?
Only if another mechanism, such as an outer deadline or abort signal, still bounds the operation.
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.
