Set timeout in a wait call to change just that operation, use page.setDefaultTimeout(ms) for the page’s general default, or use page.setDefaultNavigationTimeout(ms) for navigation operations. Puppeteer timeout values are milliseconds. The current Puppeteer 25.12.0 reference documents a 30,000 ms default for WaitForOptions; setting a documented timeout to 0 disables it.
Set the timeout for one wait
Pass a timeout option to the specific wait that needs a different limit. This avoids changing timeout behavior for unrelated page operations.
As an Amazon Associate I earn from qualifying purchases.
await page.waitForSelector('.result', { timeout: 10_000 });This example allows up to 10 seconds for the selector. The value is illustrative: choose a duration that fits the page and environment rather than assuming a longer timeout will resolve a slow or failing condition. Puppeteer documents WaitForOptions.timeout in milliseconds, with a 30,000 ms default, and says 0 disables the timeout: WaitForOptions API reference.
Choose the right timeout scope
| Scope | API | What it changes |
|---|---|---|
| One wait | timeout in the method’s options |
Only that operation; the applicable wait options document the default and whether zero disables it. See the WaitForOptions reference. |
| General page default | page.setDefaultTimeout(ms) |
The page’s default maximum time for applicable operations. See the Page.setDefaultTimeout reference. |
| Navigation default | page.setDefaultNavigationTimeout(ms) |
The default for goBack, goForward, goto, reload, setContent and waitForNavigation. See the Page.setDefaultNavigationTimeout reference. |
| Locator actions | locator.setTimeout(ms) |
The total timeout for actions on that locator. Its default comes from Page.getDefaultTimeout(); zero disables it. See the Locator.setTimeout reference. |
Set a page or navigation default
General page timeout
Set the page default when multiple applicable operations should share a timeout. The argument is in milliseconds.
#1 Best Overall
page.setDefaultTimeout(10_000);Use this for general page operations rather than assuming it is the best way to tune navigation. The API reference describes it as changing the page’s default maximum time: Page.setDefaultTimeout.
Navigation timeout
Use the navigation-specific setter when the operations you need to adjust are navigation methods. Its documented scope is goBack, goForward, goto, reload, setContent and waitForNavigation.
page.setDefaultNavigationTimeout(20_000);See Page.setDefaultNavigationTimeout for the method’s scope.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Set a locator action timeout
For locator-based interactions, set the timeout on the locator. setTimeout() returns a cloned locator with the specified total timeout for its actions.
const button = page.locator('button.submit').setTimeout(10_000);
await button.click();If you do not set a locator timeout, its default comes from the page’s default timeout. A value of 0 disables the locator timeout; use it only if waiting indefinitely is intentional. See the Locator.setTimeout API reference.
Wait for a selector to appear or disappear
waitForSelector(selector, options) resolves when the selector matches, including immediately if it already exists. If it does not appear before the timeout, the method throws. Its options include timeout, visible, hidden and an abort signal, and the wait works across navigations. For a hidden-state wait, the promise may resolve to null if the selector is not found.
Rank #3
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
// Wait up to 8 seconds for an element to exist and be visible.
await page.waitForSelector('.result', {
visible: true,
timeout: 8_000,
});
// Wait up to 8 seconds for a loading indicator to disappear.
await page.waitForSelector('.loading', {
hidden: true,
timeout: 8_000,
});See the Page.waitForSelector reference for its options and outcomes.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Wait for navigation after a click without a race
If a click triggers navigation, start waiting for navigation before issuing the click. Otherwise, a fast navigation can begin before Puppeteer starts listening for it. The documented pattern is Promise.all():
const [response] = await Promise.all([
page.waitForNavigation({ timeout: 20_000 }),
page.click('a.next'),
]);The navigation wait is registered first in the array, so it can observe the navigation initiated by the click. See the Page.waitForNavigation reference.
Handle timeouts deliberately
- Keep units clear: Puppeteer timeout values here are milliseconds;
10_000means 10 seconds. - Prefer the narrowest scope: override one wait when only that operation differs; change a page default only when several applicable operations should share it.
- Use zero sparingly: on the cited options and locator timeout,
0disables the limit. That can leave a run waiting indefinitely, so choose it only when indefinite waiting is intended. - Treat a timeout as a signal: it means the expected condition did not finish in time. Raising the limit may be appropriate for a known slow operation, but does not itself fix a missing selector, failed navigation or other underlying problem.
Troubleshooting common timeout problems
The wait still ends at the old timeout
Check which timeout scope controls that operation. A navigation method may use the navigation default; a locator action uses its locator timeout, which otherwise comes from the page default. For a one-off wait, pass the timeout directly in that call’s options.
waitForSelector() throws
The selector did not appear before the configured limit. Confirm that the selector matches the page’s actual markup and that the page reached the state where it should exist. If it is genuinely slow, adjust that wait’s timeout rather than changing every operation by default.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteA click succeeds but the navigation wait fails
Register waitForNavigation() before the click with the Promise.all() pattern above. Also confirm that the click is expected to cause navigation; an in-page update that does not navigate is a different condition to wait for.
The script hangs after setting timeout to zero
Zero disables the timeout where documented, so Puppeteer has no time limit to end that wait. Restore a finite timeout unless waiting forever is intentional.
Or skip the browser setup
If the goal is a screenshot rather than browser automation, ScreenshotNeo can return an image or PDF with one GET request. For example, using cURL:
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. Cookie banners, popups and chat widgets are removed before the shot; bot checks, blank pages and failed loads are never billed; an MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for free.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
What is Puppeteer’s default wait timeout?
The current Puppeteer 25.12.0 WaitForOptions reference lists 30,000 milliseconds (30 seconds).
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.
