Puppeteer Wait Timeout Options Explained

Direct answer: Puppeteer timeout values are milliseconds. For one selector wait, pass timeout in its options. To change defaults, use page.setDefaultTimeout() for general waits or page.setDefaultNavigationTimeout() for navigation methods. In current Puppeteer v25.12.0 documentation, waitForSelector and waitForNavigation default to 30,000 ms. Check your installed Puppeteer version because defaults and types can differ across versions.

Choose the timeout by scope

Need	Use	Scope
Adjust one selector wait	`waitForSelector(selector, { timeout })`	One call
Set a general page default	`page.setDefaultTimeout(ms)`	General page waits
Set a navigation default	`page.setDefaultNavigationTimeout(ms)`	Navigation methods documented by Puppeteer
Limit one locator action	`locator(selector).setTimeout(ms)`	That locator

Use a bounded timeout that matches the slowest acceptable response for your workflow. A timeout is a maximum, not a delay: if the condition is already satisfied, the wait can finish immediately.

Runnable JavaScript example

This CommonJS example launches Chromium, navigates to a page, waits for a selector with a local limit, and closes the browser even if a wait fails. Install Puppeteer with npm install puppeteer; the package downloads a compatible browser by default.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();

    // General page waits use this default unless locally overridden.
    page.setDefaultTimeout(15_000);

    // Navigation methods use this separate default.
    page.setDefaultNavigationTimeout(45_000);

    await page.goto('https://example.com', {
      waitUntil: 'domcontentloaded',
    });

    // This call overrides the general default for this selector wait.
    const result = await page.waitForSelector('h1', { timeout: 10_000 });
    console.log('Found heading:', Boolean(result));
    await result.dispose();

    // A locator can have its own timeout for an interaction.
    await page.locator('h1').setTimeout(5_000).wait();
  } finally {
    await browser.close();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

The example demonstrates the documented option shapes; it is not a claim that the code was run in a particular project. If your package version does not expose a shown API or type, consult the matching version’s API reference.

Per-call timeout options

waitForSelector

The current documented default is 30,000 ms. Pass a local value when this selector is predictably faster or slower than other waits:

await page.waitForSelector('#results', { timeout: 8_000 });

Pass 0 to disable the timeout for this API. Use that only when an unbounded wait is acceptable; a missing selector can otherwise leave a job waiting indefinitely.

Visibility options change the condition being awaited:

// Wait for the element to exist and be visible.
await page.waitForSelector('#menu', { visible: true, timeout: 5_000 });

// Wait until the element is hidden or absent.
const hiddenResult = await page.waitForSelector('#loading', {
  hidden: true,
  timeout: 10_000,
});
// When hidden: true, a missing selector can resolve to null.
console.log(hiddenResult === null);

When a selector wait returns an ElementHandle, dispose of it when you are finished if it is no longer needed. For typical interactions, Puppeteer’s current guide recommends locators.

waitForNavigation

The documented default navigation timeout is 30,000 ms. You can override the duration on a single call and choose a lifecycle condition separately:

await page.waitForNavigation({
  timeout: 45_000,
  waitUntil: 'domcontentloaded',
});

timeout caps how long the wait can run. waitUntil describes what navigation lifecycle event or events must occur. It accepts one event or an array; with an array, the wait succeeds after all listed events have fired. Choose a lifecycle condition appropriate to the page rather than increasing the timeout to compensate for waiting for the wrong event.

When a click triggers navigation, start waiting before the click so the navigation event is not missed:

await Promise.all([
  page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 30_000 }),
  page.click('a.next'),
]);

Locator timeout

Locators inherit the page timeout by default. Set a local limit for an interaction when appropriate:

await page.locator('button[type="submit"]').setTimeout(5_000).click();

Locator timeout 0 disables its timeout according to the current guide. Locators are generally preferable for interactions because they handle waiting and retrying around the action; use waitForSelector when you specifically need the lower-level element wait.

Use page.setDefaultTimeout(milliseconds) when many general waits on the page should share a different default:

page.setDefaultTimeout(15_000);

Use page.setDefaultNavigationTimeout(milliseconds) to set the navigation default for goBack, goForward, goto, reload, setContent, and waitForNavigation:

page.setDefaultNavigationTimeout(45_000);

The navigation setter controls the documented navigation method set; it does not replace the general page timeout for selector waits. A per-call timeout is useful when one operation needs an exception to either default. The arguments are milliseconds.

How to diagnose a timeout

Identify the exact operation. Is it waiting for a selector, an interaction, or navigation?
Check its condition. For selectors, confirm the selector matches the rendered DOM and whether you need presence, visibility, or hidden/absent state. For navigation, choose the right waitUntil lifecycle event.
Check which default applies. A navigation default and a general page default have different scopes.
Use a local timeout first. If only one call is slow, override that call rather than raising every wait.
Check the installed version and types. The cited defaults reflect current v25.12.0 docs, not necessarily your dependency.

Troubleshooting common timeout problems

Symptom	Likely cause	Fix
`waitForSelector` times out at about 30 seconds	The call uses the documented 30,000 ms default, or the element never satisfies the condition.	Verify the selector and state. If the condition is correct but slower, set a suitable local `timeout`.
Increasing navigation timeout does not help a selector wait	`setDefaultNavigationTimeout()` applies to the documented navigation methods, not general selector waits.	Set `setDefaultTimeout()` or provide a timeout directly to the selector wait.
Navigation times out even though the page appears changed	The selected `waitUntil` event may not match the page’s loading behavior, or the navigation wait may have started after the triggering action.	Pick an appropriate lifecycle event and start the wait before the click or action that triggers navigation.
Waiting for a hidden element returns `null`	With `hidden: true`, Puppeteer can resolve to `null` when the selector is absent.	Treat `null` as a valid hidden/absent result; use the returned handle only when one exists.
The script hangs after setting timeout to zero	Zero disables the timeout for APIs that document this convention.	Use a finite value or add an independent job-level deadline and cancellation strategy.
TypeScript rejects an option or method	The installed version or its type definitions differ from the current documentation.	Check the lockfile and installed package version, then consult that version’s API docs.

Performance, reliability, and cost

Longer timeouts do not make a page load faster; they allow a slow or stalled condition more time before failure. Excessively high limits can tie up browser processes and workers, especially when many pages wait concurrently. Prefer specific conditions, finite timeouts, and cleanup in finally blocks so a failed wait does not leave browser resources open.

For reliable automation, choose the narrowest condition that indicates the task is ready. Waiting for a broad lifecycle event can be inappropriate for pages with ongoing network activity; waiting only for a selector can also be insufficient if the element exists before it is usable. Keep retries bounded and make them safe to repeat. Puppeteer itself does not define a per-timeout price in the cited API documentation; compute your operational cost from your hosting, browser runtime, and concurrency limits.

Or skip the browser setup

If the task is to capture a page rather than interact with it, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, 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}`);

Cookie banners are accepted and removed before capture; newsletter popups and chat widgets are removed too. Each step can be turned off.
Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers indicate the page verdict and billing status.
An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots.

FAQ

What is the default Puppeteer timeout?

The current v25.12.0 documentation gives waitForSelector and waitForNavigation a 30,000 ms default. Check the documentation for your installed version.

Does timeout mean Puppeteer waits that long every time?

No. It is a maximum. A wait can resolve as soon as its condition is met.

Can I turn off timeouts?

For APIs that document the convention, pass 0. An unbounded wait can hang when its condition never occurs.

Where can I confirm the option names?

Use the official waitForSelector API reference, waitForNavigation API reference, and page interactions guide, matching the version installed in your project.