Puppeteer timeouts are measured in milliseconds. For one wait, set its timeout option; for page-wide defaults, use page.setDefaultTimeout(); and for navigation methods, use page.setDefaultNavigationTimeout(). In the current Puppeteer v25.12.0 documentation, waitForSelector and waitForNavigation default to 30,000 ms (30 seconds). Check your installed Puppeteer version because its API behavior may differ.
Choose the timeout by scope
| What needs a different limit? | Use | Scope and notes |
|---|---|---|
| One selector wait | page.waitForSelector(selector, { timeout: milliseconds }) |
Overrides the limit for that call. The documented default is 30,000 ms in Puppeteer v25.12.0; 0 disables the timeout for this API. |
| General page waits | page.setDefaultTimeout(milliseconds) |
Sets the page’s general timeout default, including selector waits unless a local option overrides it. |
| Navigation methods | page.setDefaultNavigationTimeout(milliseconds) |
Sets the default for goBack, goForward, goto, reload, setContent, and waitForNavigation. |
| A locator action | locator.setTimeout(milliseconds) |
Sets a local locator limit. Locators inherit the page timeout by default; 0 disables the locator timeout. |
The timeout is a maximum, not a delay: if the requested condition is already true, Puppeteer can resolve the wait immediately. The API references describe the defaults and supported options: waitForSelector options, waitForNavigation options, and navigation timeout default.
Set a timeout for one selector wait
Use a local override when only one selector is slower or faster than the rest of the page’s waits. The value is in milliseconds.
const result = await page.waitForSelector('#result', { timeout: 10_000 });This waits for #result for up to 10 seconds. If the selector already matches, the promise can resolve sooner. In the documented API, use timeout: 0 to disable the timeout for this wait; do that only when an unbounded wait is acceptable.
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 & 11#1 Best Overall
Presence, visibility, and absence are different conditions
By default, waitForSelector waits for the selector to exist in the DOM. Set visible: true to wait for a matching element to be present and visible. Set hidden: true to wait until it is hidden or absent; when no matching element is found, that mode resolves to null. These condition options change what Puppeteer is waiting for, not the timeout limit.
await page.waitForSelector('.loading', { hidden: true, timeout: 15_000 });Where suitable, dispose of a returned ElementHandle after use. For typical element interaction, Puppeteer’s current guide recommends Locators instead.
Set page-wide defaults
General waits
Call setDefaultTimeout to change the page’s general timeout default. The argument is milliseconds:
page.setDefaultTimeout(15_000);A local timeout passed to a particular wait remains the better choice when only that operation needs a different limit.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Navigation waits
Call setDefaultNavigationTimeout to change the navigation default:
page.setDefaultNavigationTimeout(45_000);The documented methods governed by this setting are goBack, goForward, goto, reload, setContent, and waitForNavigation. A selector wait is a general wait, so increasing the navigation default alone does not change its timeout.
Rank #3
Use Locators for element interactions
Locators inherit the page timeout by default. For an action that needs its own limit, set it on the locator:
await page.locator('button').setTimeout(5_000).click();This example caps the locator operation at 5 seconds. Locator timeout behavior and the recommendation to use Locators for interactions are covered in Puppeteer’s page interactions guide.
Configure navigation condition separately
For waitForNavigation, timeout caps how long Puppeteer waits. waitUntil specifies which navigation lifecycle event or events must occur. These settings solve different problems.
await page.waitForNavigation({
timeout: 45_000,
waitUntil: 'domcontentloaded',
});waitUntil accepts one lifecycle event or an array of events. With an array, the wait succeeds after all listed events have fired. The documented default for waitForNavigation’s timeout is 30,000 ms in Puppeteer v25.12.0. Choose the lifecycle condition that matches the page’s behavior rather than simply raising the time limit.
Diagnose a wait that times out
- The selector never appears: Confirm the selector matches the actual DOM and that the page reached the state where it should appear. Increase the local timeout only if the element legitimately takes longer to arrive.
- The element exists but the wait still fails: Check whether you requested visibility or hidden state.
visible: truerequires visibility;hidden: truewaits for hidden or absent state. - Navigation seems complete but the wait times out: Review
waitUntil. A later lifecycle event can take longer or may not occur for the kind of navigation involved. Set a condition appropriate to the page, separately from the maximum timeout. - Changing the navigation default has no effect on a selector wait: Use
setDefaultTimeoutfor general waits or set the selector call’s owntimeout. - The option or type does not behave as documented: Check the Puppeteer version in the project’s dependency lockfile and consult documentation for that version. The defaults cited here are from v25.12.0, not a guarantee for every installed release.
- An unlimited wait appears stuck: If the API supports
timeout: 0, it removes the time limit; it does not make the awaited condition happen. Prefer a finite bound when a script needs to fail and recover.
Or skip the browser setup
If the goal is a screenshot rather than browser automation, ScreenshotNeo provides a website screenshot API and MCP server. Its one-call GET request can return an image or PDF:
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 options and response details. It accepts cookie or 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 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 provides take_screenshot, get_page_info, and capture_pdf for AI agents using Claude, Cursor, or another MCP client. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to start with 1,000 screenshots a month and no card.
Frequently Asked Questions
What is the default Puppeteer timeout for waitForSelector?
The current v25.12.0 documentation lists 30,000 ms (30 seconds). Check the documentation matching your installed Puppeteer version.
Can I disable a Puppeteer wait timeout?
For APIs that document the convention, pass timeout: 0. This removes the time limit, not the condition being awaited.
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.
