How to Set a Default Timeout in Puppeteer

Set a default timeout for applicable waits on a Puppeteer page with page.setDefaultTimeout(milliseconds). The value is in milliseconds: page.setDefaultTimeout(10_000) sets a 10-second default. Use page.setDefaultNavigationTimeout() when you want to set the limit specifically for navigation operations, or pass timeout to one operation when only that wait needs a different limit.

Runnable example: set a page-wide default

Install Puppeteer in a Node.js project with npm install puppeteer. Save this as timeout-example.mjs and run it with node timeout-example.mjs. Change the URL and selector to match the page you need.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();

  // Set a 10-second default for applicable waits on this Page.
  page.setDefaultTimeout(10_000);

  await page.goto('https://example.com');
  await page.waitForSelector('h1');

  console.log('Default timeout:', page.getDefaultTimeout(), 'ms');
  console.log('Page title:', await page.title());
} finally {
  await browser.close();
}

The setter returns void; it configures the Page object on which you call it. It does not take seconds, a duration string, or an options object. The official API describes the parameter as a maximum time in milliseconds. See the [Puppeteer Page.setDefaultTimeout API](https://pptr.dev/api/puppeteer.page.setdefaulttimeout) and the [Page reference](https://pptr.dev/api/puppeteer.page).

Pick the right timeout scope

Scope	Use	Example
Applicable waits on a Page	Set a shared default for supported waits.	page.setDefaultTimeout(10_000)
Navigation operations	Set a navigation limit explicitly for navigation methods.	page.setDefaultNavigationTimeout(20_000)
One operation	Give a specific call a different limit.	page.waitForSelector('.result', { timeout: 5_000 })

General waits with setDefaultTimeout

page.setDefaultTimeout(ms) changes the default maximum wait time used by applicable page operations. You can inspect the configured general value with page.getDefaultTimeout(). It is a page-level setting, so configure each Page whose waits should use it.

Navigation waits with setDefaultNavigationTimeout

Use the navigation-specific setter when you want the intent and scope to be clear:

page.setDefaultNavigationTimeout(20_000); // 20 seconds for navigation waits
console.log(page.getDefaultNavigationTimeout());

The documented navigation operations are goBack, goForward, goto, reload, setContent, and waitForNavigation. Puppeteer’s Page reference also says that setDefaultTimeout can change the default navigation timeout. If you configure both setters, check page.getDefaultTimeout() and page.getDefaultNavigationTimeout() on your installed version and set the values deliberately; the navigation-specific setter makes the navigation limit explicit. See [Page.setDefaultNavigationTimeout](https://pptr.dev/api/puppeteer.page.setdefaultnavigationtimeout) and [Page.getDefaultNavigationTimeout](https://pptr.dev/api/puppeteer.page.getdefaultnavigationtimeout).

One-operation override

When only one wait needs a different limit, pass its timeout option instead of changing the page-wide policy:

// Wait up to 5 seconds for this selector only.
await page.waitForSelector('.search-result', { timeout: 5_000 });

// Wait up to 45 seconds for this navigation only.
await page.goto('https://example.com/report', {
  waitUntil: 'domcontentloaded',
  timeout: 45_000,
});

Confirm that the method you are calling supports a timeout option. For example, Puppeteer documents a 30-second default for waitForSelector, and says its default can be changed with Page.setDefaultTimeout(). Navigation wait options document a 30-second default and allow the page timeout setters to change it. Consult the [waitForSelector options](https://pptr.dev/api/puppeteer.waitforselectoroptions) and [wait options](https://pptr.dev/api/puppeteer.waitforoptions) for the exact operation and Puppeteer version you use.

Configure navigation and general waits together

A common policy is a moderate default for ordinary waits, a longer navigation budget for slow sites, and a short one-off wait for a known quick element:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();

  page.setDefaultTimeout(10_000);
  page.setDefaultNavigationTimeout(30_000);

  await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
  await page.waitForSelector('h1');
  await page.waitForSelector('.optional-widget', {
    timeout: 2_000,
    hidden: true,
  });

  console.log({
    defaultTimeout: page.getDefaultTimeout(),
    navigationTimeout: page.getDefaultNavigationTimeout(),
  });
} finally {
  await browser.close();
}

Here hidden: true waits for the selector to be absent or hidden; it is useful for a loading indicator that should disappear. It does not wait for the element to become visible. For an element that must appear and be visible, use { visible: true }. If a selector is already present, waitForSelector resolves immediately; if a requested selector does not meet the condition before the timeout, the wait rejects. See the [waitForSelector reference](https://pptr.dev/api/puppeteer.page.waitforselector).

Choosing a duration and wait condition

• Start with the shortest useful limit. A timeout bounds how long the operation can wait; it does not make the page or network faster.
• Use milliseconds. 1_000 is one second, 10_000 is ten seconds, and 30_000 is thirty seconds.
• Keep navigation and application readiness distinct. A navigation event says the chosen browser lifecycle condition occurred. If the application renders important content afterward, also wait for a meaningful selector or response.
• Choose waitUntil intentionally. Navigation options accept lifecycle event conditions. Waiting for a less strict milestone such as domcontentloaded can be suitable when the page continues loading long-lived resources, but it does not prove that your target content is ready.
• Prefer a specific readiness signal. Wait for the element or response your next step requires instead of adding a large delay to every operation.

Disable a supported timeout

For wait options that document this behavior, pass 0 to disable the timeout. For example:

page.setDefaultTimeout(0); // Disable timeout for applicable waits
await page.waitForSelector('.eventually-available');

You can also disable a single supported operation timeout with { timeout: 0 }. This means the wait can continue indefinitely unless it succeeds or is otherwise cancelled. Use it only when that behavior is intentional and your surrounding job has another way to stop or recover. A finite timeout is generally easier to operate in scripts and services.

Timeout errors: causes and fixes

Symptom	Likely cause	What to do
TimeoutError from waitForSelector	The selector never appeared, the selector is wrong, or it appeared in a different frame.	Inspect the rendered DOM, check the selector and frame, and wait for the actual readiness condition. Increase the per-call or page default only if the operation legitimately needs more time.
TimeoutError from goto or waitForNavigation	The selected navigation lifecycle condition was not reached in time, or the site is slow or keeps resources open.	Choose an appropriate waitUntil milestone, check navigation behavior, and configure the navigation timeout or per-call timeout for that operation.
Timeout appears unchanged after setting a value	The setter was called on a different Page, the operation has its own timeout, or the call does not use that page default.	Set it on the same page before the wait, inspect with the corresponding getter, and consult that method’s options reference.
Wait never returns	A zero timeout disabled the limit, or the awaited condition cannot occur.	Restore a finite timeout and verify the condition can become true. If disabling was intentional, ensure the task has a separate cancellation or deadline mechanism.
Value is far shorter or longer than expected	Seconds were supplied where milliseconds are required.	Convert seconds to milliseconds: for example, 15 seconds is 15_000.
Wait succeeds, but later page content is missing	The chosen selector or navigation milestone occurred before the application finished the work you care about.	Wait for the specific rendered content or network response needed by the next step; a generic navigation timeout does not define application readiness.

Performance, reliability, and cost

Timeout configuration does not consume a separate Puppeteer feature or change browser speed. Its practical effect is how long a job can remain waiting before the operation fails. Shorter limits can help a worker move past genuinely stuck pages sooner, but limits that are too short cause avoidable failures on slow or variable pages. Larger limits reduce premature timeouts at the cost of allowing a stalled task to occupy resources longer. A disabled timeout can leave a task waiting without an operation-level deadline.

For reliable automation, choose a timeout from the task’s expected conditions, keep navigation and element readiness separate, and handle timeout failures explicitly. In a batch job, catch failures per URL so one slow page does not prevent cleanup or reporting for other work. Always close the browser in a finally block, as in the examples. The appropriate value depends on your site, environment, and operation; the cited API references do not provide a universal performance benchmark or recommended custom value.

Or skip the browser setup

If your task is simply to capture a page image or PDF, [ScreenshotNeo](https://screenshotneo.com) provides a website screenshot API and MCP server. A single GET request returns PNG, JPEG, WebP, or PDF. Its [API documentation](https://screenshotneo.com/docs/) describes the available parameters.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie banners, newsletter popups, and chat widgets are removed before the shot; those cleanup steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are never billed, and response headers report the page verdict and billing status. The MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Every feature is on every plan. [Create a free account](https://screenshotneo.com/account/sign-up/).

FAQ

Does setDefaultTimeout take seconds?

No. It takes milliseconds. Use 10_000 for ten seconds.

What is Puppeteer’s default wait timeout?

The reviewed Puppeteer wait option references document 30 seconds for options such as selector and navigation waits. Check the API reference matching your installed Puppeteer version.

Does setDefaultTimeout apply to every timeout in Puppeteer?

No. It changes defaults for applicable Page operations. Browser launch settings and methods with their own timeout configuration have separate options; check the relevant method reference.

How can I check the configured value?

Call page.getDefaultTimeout() for the general page timeout and page.getDefaultNavigationTimeout() for the navigation timeout.

References

• Puppeteer: Page.setDefaultTimeout
• Puppeteer: Page.setDefaultNavigationTimeout
• Puppeteer: Page.getDefaultTimeout
• Puppeteer: Page.getDefaultNavigationTimeout
• Puppeteer: WaitForSelectorOptions
• Puppeteer: WaitForOptions

API version note: the official method and option pages reviewed show different Puppeteer version labels. Verify behavior against the documentation for the version installed in your project.