Use page.setDefaultTimeout(ms) to change a page’s general wait timeout, and page.setDefaultNavigationTimeout(ms) to change the default for navigation methods such as page.goto(). Both values are in milliseconds. For just one operation, pass its own timeout option.
Choose the timeout that matches the operation
| What you want to change | Use | Scope |
|---|---|---|
| Default for page waits that support it | page.setDefaultTimeout(ms) |
The Page instance and applicable methods or wait options; check each method’s documentation. |
| Default for navigation | page.setDefaultNavigationTimeout(ms) |
goBack(), goForward(), goto(), reload(), setContent(), and waitForNavigation(). |
| One method call | The method’s { timeout: ms } option |
That specific call. |
| One locator’s actions | locator.setTimeout(ms) |
That locator; its default comes from Page.getDefaultTimeout(). |
| Browser startup | puppeteer.launch({ timeout: ms }) |
Launching the browser, not waits on a page that already exists. |
The Puppeteer documentation for common wait options lists 30,000 ms (30 seconds) as the default. These APIs are version-sensitive; consult the API documentation matching your installed Puppeteer release if behavior or method availability differs.
As an Amazon Associate I earn from qualifying purchases.
Set page-wide defaults for a Page
Call the setters on the Page object before the operations you want them to govern. They configure that page, not every page in the process.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
const page = await browser.newPage();
// General page wait default, in milliseconds.
page.setDefaultTimeout(60_000);
// Navigation default, also in milliseconds.
page.setDefaultNavigationTimeout(60_000);
await page.goto('https://example.com');
await page.waitForSelector('main');
await browser.close();Here, waits using the general default can wait up to 60 seconds, and navigations covered by the navigation setter have a 60-second maximum. Use a value appropriate to the operation rather than increasing every timeout automatically.
#1 Best Overall
For page.goto()
page.goto() is a navigation, so page.setDefaultNavigationTimeout(ms) is the focused page-level setting. If only one navigation needs a different limit, use its per-call timeout option instead. The navigation setter also covers goBack(), goForward(), reload(), setContent(), and waitForNavigation().
For waitForSelector()
Use page.setDefaultTimeout(ms) for the general page default, or pass a local timeout: await page.waitForSelector('main', { timeout: 10_000 });. The selector wait resolves immediately if the selector already matches; if it does not appear before the applicable timeout, the wait throws.
Rank #2
Override the timeout for a single operation
A method-level option is the clearest choice when one call needs a different limit from the rest of the page:
await page.goto('https://example.com/report', { timeout: 90_000 });
await page.waitForSelector('[data-ready="true"]', { timeout: 15_000 });Use the option name and units documented for the particular method. Setting a local option avoids changing the page’s defaults for unrelated work.
Use zero only when you intend to disable the timeout
The documented wait options allow timeout: 0 to disable the timeout for that wait. This can be useful when another control mechanism is responsible for ending the operation, but it can also leave a stalled wait pending if nothing else cancels or resolves it. Do not use zero as a routine fix for slow or failing pages.
Keep startup and locator timeouts separate
Browser launch
puppeteer.launch({ timeout: ms }) controls browser startup. The LaunchOptions reference documents a 30,000 ms default. This is not a substitute for page wait or navigation settings.
Locator actions
For a locator-specific action limit, use locator.setTimeout(ms). The locator timeout documentation describes a cloned locator and says its default is derived from Page.getDefaultTimeout().
Free tools Windows power users keep installed
One-click scans. No signup required.
Troubleshoot timeout errors
page.goto()times out: Confirm the page-level navigation timeout is set on the samePageinstance, or pass a largertimeoutto that call. A timeout only changes how long Puppeteer waits; it does not repair a URL, network, or page-load problem.waitForSelector()times out: Check that the selector is correct and that the element is expected to appear in the page state being queried. Increase the limit only if the page legitimately needs more time.- Changing the default appears to do nothing: Verify that the setter runs before the wait, that it is called on the page performing the work, and that the method uses that default. A method-level timeout may be the more appropriate explicit control for a single call.
- Browser startup fails despite a longer page timeout: Adjust the separate
puppeteer.launch({ timeout: ms })option; page settings apply after a page exists. - A wait never finishes after setting zero: Restore a finite timeout or add deliberate cancellation/control flow so the operation can end.
- Documentation and installed package differ: Check the API reference for the version actually installed. Puppeteer documentation pages may show different minor versions, so do not assume every historic release has identical methods or behavior.
Or skip the browser setup
If your goal is simply to produce a screenshot rather than control Puppeteer itself, ScreenshotNeo provides a one-request API. It accepts a URL and returns a screenshot or PDF. Its cleanup steps accept cookie and consent banners and remove known consent platforms, newsletter popups, and chat widgets before capture; these steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, with response headers indicating the page verdict and billing status. It also offers an MCP server for AI agents.
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. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up free for 1,000 screenshots a month, with no card.
Quick Recap
Best Value
Sources
- Puppeteer Page.setDefaultTimeout
- Puppeteer Page.setDefaultNavigationTimeout
- Puppeteer WaitForSelectorOptions
- Puppeteer WaitForOptions
- Puppeteer LaunchOptions
- Puppeteer Locator.setTimeout
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.
