How to Set Default Timeouts in Puppeteer

Use page.setDefaultTimeout(ms) to change the default for supported waits on one Puppeteer page. Use page.setDefaultNavigationTimeout(ms) for navigation operations such as page.goto(), page.reload(), and page.waitForNavigation(). Values are milliseconds. To change only one operation, pass its own timeout option.

Common wait APIs document a default of 30,000 ms (30 seconds). Check the API documentation for your installed Puppeteer version if a method behaves differently. The timeout setters belong to a Page instance; configure each page that needs the setting. See the official references for Page.setDefaultTimeout, Page.setDefaultNavigationTimeout, and WaitForSelectorOptions.

Choose the timeout setting for the operation

What you need	Setting	Scope
Change the default for supported waits on a page	`page.setDefaultTimeout(ms)`	The page’s general default for methods and wait options that use it. Check each method’s documentation.
Change the default for page navigation	`page.setDefaultNavigationTimeout(ms)`	`goBack`, `goForward`, `goto`, `reload`, `setContent`, and `waitForNavigation`.
Change one operation only	`{ timeout: ms }`	That individual call, where the method accepts a timeout option.
Set a timeout for locator actions	`locator.setTimeout(ms)`	That locator. See the Locator.setTimeout reference.
Change the browser startup timeout	`puppeteer.launch({ timeout: ms })`	Browser launch, before a page exists. See LaunchOptions.

Use the navigation setter when the issue is a navigation. For a single navigation that needs a different limit, use that method’s per-call option. An explicit operation-level timeout makes the intended limit clear for that call.

Set defaults in a runnable Puppeteer script

This ES module example sets both page defaults, navigates to a page, and waits for a selector. Install Puppeteer with npm install puppeteer, save the code as timeouts.mjs, and run node timeouts.mjs.

import puppeteer from 'puppeteer';

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

  // General default for supported waits on this Page, in milliseconds.
  page.setDefaultTimeout(60_000);

  // Navigation default, also in milliseconds.
  page.setDefaultNavigationTimeout(60_000);

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

  console.log(await page.title());
} finally {
  await browser.close();
}

The setters configure the page you call them on; they do not set one process-wide timeout for all pages. Configure each page after creating it, before starting the operations whose defaults you want to change.

Override the timeout for one operation

Use an operation’s own timeout option when a single wait needs a shorter or longer limit than the page default. This avoids changing the behavior of other waits on that page.

// Wait up to 10 seconds for this selector only.
await page.waitForSelector('main', { timeout: 10_000 });

// Allow this navigation up to 90 seconds, if supported by the installed API.
await page.goto('https://example.com/slow-page', { timeout: 90_000 });

Check the individual method’s documentation for supported options and behavior. Puppeteer’s wait option references document 30,000 ms as the common default; a method-specific option overrides the default for its call. See the official selector wait options and Page.goto documentation.

Understand which timeout is expiring

Page waits

page.setDefaultTimeout(ms) is a page-level default for supported APIs that use the page timeout. It is useful for waits such as selector and function waits. It does not automatically control every timeout in Puppeteer: consult the remarks for the specific API.

page.setDefaultNavigationTimeout(ms) is the navigation-specific default. The API documentation lists goBack(), goForward(), goto(), reload(), setContent(), and waitForNavigation(). A page navigation can take longer than an element wait, so tune the relevant scope instead of raising every wait limit without distinction.

Browser startup and locator actions

puppeteer.launch({ timeout: ms }) sets the browser startup timeout; it is separate from page timeouts. Locator actions have their own locator.setTimeout(ms) option. These distinctions matter when the browser fails to launch or a locator action times out even though other page waits have a longer default.

Disable a timeout only when necessary

For wait options that document it, setting timeout: 0 disables that wait’s timeout. This can be useful when another mechanism controls cancellation or completion. Without an active timeout, a stalled wait can remain pending until other control flow or cancellation intervenes.

// Use only when another part of the program guarantees completion or cancellation.
await page.waitForSelector('#ready', { timeout: 0 });

Prefer a finite timeout for routine automation. An unlimited wait can keep a job occupied indefinitely if the selector never appears or the page stops progressing.

Troubleshoot timeout failures

Symptom	Likely cause	What to check or change
`Navigation timeout of ... exceeded`	The page did not satisfy the navigation wait before its navigation limit.	Set `page.setDefaultNavigationTimeout(ms)` for the page, or pass a per-call timeout to `goto()`. Also check whether the chosen navigation wait condition matches the page’s behavior.
`Waiting for selector ... failed`	The selector did not match before the wait expired, or the wrong page/frame is being inspected.	Check the selector, confirm the page has reached the expected state, and use a longer `waitForSelector` timeout only if the content legitimately takes longer.
Increasing the general timeout does not fix `goto()`	The operation is navigation-specific, or a local option is setting the effective limit.	Use the navigation setter for navigation defaults and inspect the call’s own options.
A wait still uses the old limit	The setting was applied to a different `Page`, applied after the wait began, or the method uses a different timeout scope.	Set the timeout on the same page before starting the operation. Check that method’s API reference and the installed Puppeteer version.
Browser launch times out before a page is created	This is browser startup, not a page wait.	Configure `puppeteer.launch({ timeout: ms })` and investigate why browser startup is slow or blocked.
Locator action times out despite page settings	The locator has its own timeout setting or the action’s behavior differs from the wait being configured.	Inspect the locator API and configure the locator with `locator.setTimeout(ms)` if appropriate.

A timeout increase changes how long Puppeteer waits; it does not make an absent selector appear or repair a stalled navigation. Confirm the expected page state and the specific API’s wait condition before increasing the limit.

Performance, reliability, and cost

Performance: Longer limits do not slow a successful operation that finishes earlier, but they can keep failed or stuck jobs occupied longer. Use longer limits only for operations known to need them.
Reliability: Keep finite limits and handle timeout errors at the operation boundary so one slow page does not block the entire workflow. Close pages and browsers in cleanup paths.
Cost: Puppeteer’s timeout setters do not have a separate API charge, but browser runtime and infrastructure can cost money. A larger timeout can extend resource use when a page does not finish promptly.
Version compatibility: The cited references include multiple Puppeteer documentation versions. Verify method availability and options against the version installed in your project.

Or skip the browser setup

If your goal is to capture a page rather than automate a browser, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF. See the ScreenshotNeo API documentation.

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 import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers say which outcome occurred. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Are Puppeteer timeouts measured in seconds?

No. The timeout arguments are milliseconds: 30_000 is 30 seconds and 60_000 is 60 seconds.

Does `setDefaultTimeout()` change every page?

No. It is called on a Page instance. Apply it to each page that needs that default.

What is the documented default timeout?

The cited common wait option references document 30,000 ms. Defaults and API behavior can vary by method and Puppeteer release, so check the documentation for your installed version.

Can I give one selector wait a different timeout?

Yes. Pass { timeout: ms } to that wait, such as page.waitForSelector('main', { timeout: 10_000 }).