How to Set a Timeout for a Puppeteer Locator

Set the timeout on the locator before calling its action. The value is in milliseconds:

await page.locator('button').setTimeout(3000).click();

setTimeout() returns a new locator configured with that timeout. Use page.setDefaultTimeout() when you want a page-wide default inherited by locators that do not set their own timeout. A locator timeout applies to locator actions; it does not configure navigation timeouts. See Puppeteer’s page interactions guide and Locator.setTimeout() reference.

1. Set a timeout on one locator

Use .setTimeout(milliseconds) in the locator chain before the action. This is useful when one control takes longer to become ready than the rest of the page:

const submit = page.locator('button.submit');
await submit.setTimeout(10_000).click();

The timeout is in milliseconds. The example allows up to 10 seconds for this locator action. Choose a value that fits the page and action; Puppeteer’s documented 3,000 ms example is an API example, not a universal recommendation.

Because setTimeout() returns a cloned locator, the original locator remains unchanged. Configure the returned locator you intend to use:

const base = page.locator('button.submit');
const patientSubmit = base.setTimeout(10_000);

await patientSubmit.click();

2. Set a page-wide default

Call page.setDefaultTimeout(milliseconds) to change the page’s default timeout. Locators inherit this setting unless you override it on a specific locator:

page.setDefaultTimeout(5000);

// Inherits the page default: 5,000 ms.
await page.locator('button.cancel').click();

// This action has a per-locator timeout of 10,000 ms.
await page.locator('button.submit').setTimeout(10_000).click();

Setting	Scope	Use it when
`locator.setTimeout(ms)`	The configured locator’s actions	One element or action needs a different wait limit.
`page.setDefaultTimeout(ms)`	Page operations that use the default, including locators without an override	You want a consistent baseline across the page.
`locator.setTimeout(0)`	The configured locator	You explicitly need to disable timeout enforcement for that locator.

Puppeteer also has a separate navigation timeout API. Changing the locator timeout or the page’s default timeout does not mean you have configured navigation timeouts. See the Page.setDefaultTimeout() reference for the page default.

3. What a locator timeout covers

Locator actions wait for the target and for action readiness conditions. Depending on the action, readiness can include the element being present, visible, enabled, in the viewport, or having a stable bounding box. Puppeteer retries when readiness checks fail. If the target is not found or the required state is not reached before the timeout, the action throws a TimeoutError.

For example, clicking a button is not just a selector lookup: the button must also become ready for the click. Increasing the timeout can help when that transition legitimately takes longer, but it will not correct a selector that never matches or a page that never reaches the required state.

4. Complete runnable example

This Node.js example launches Chromium, opens a page, waits for a button using a locator-specific timeout, clicks it, and closes the browser. Install Puppeteer with npm install puppeteer, then save this as locator-timeout.js and run node locator-timeout.js. The page is intentionally local HTML so the example does not depend on a third-party site:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.setContent(`
      <!doctype html>
      <button id="ready">Continue</button>
    `);

    // Allow up to 3 seconds for this click's locator readiness checks.
    await page.locator('#ready').setTimeout(3000).click();
    console.log('Button clicked');
  } finally {
    await browser.close();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

The 3-second value is a concrete example. Set it based on the expected behavior of your page. For a page-wide baseline and one slower control, combine the settings:

page.setDefaultTimeout(5000);

await page.locator('#ordinary-control').click();
await page.locator('#slow-control').setTimeout(15_000).click();

5. Use zero carefully

Passing 0 disables timeout enforcement for that locator:

await page.locator('#eventually-ready').setTimeout(0).click();

This can leave an operation waiting indefinitely if the selector or readiness condition never succeeds. Before removing the limit, verify the selector and action preconditions. A finite timeout usually makes a stalled automation run easier to detect and recover from.

6. Troubleshoot locator timeouts

Symptom	Likely cause	What to check or change
`TimeoutError` even after increasing the limit	The selector does not match the intended element, or it never becomes ready.	Check the selector against the current DOM and confirm the target reaches the state required by the action.
The element exists but `click()` times out	The element may be hidden, disabled, outside the viewport, or still moving.	Check the click’s readiness conditions. Wait for the UI transition that makes the element actionable, or correct the page state.
One locator still uses an unexpected limit	`setTimeout()` returns a cloned locator, and the action may be using the original locator.	Chain the call directly to the action, or save and use the returned locator.
Changing the locator timeout does not fix a navigation wait	Navigation has its own timeout configuration.	Configure the navigation timeout separately; locator `setTimeout()` applies to locator actions.
A wait never ends after setting the timeout to zero	Zero disables timeout enforcement for that locator.	Use a finite value again, then investigate the selector and readiness conditions.
A longer timeout makes the run slower without fixing the failure	The target may never meet the action’s conditions.	Restore a bounded timeout and fix the selector, page state, or expected interaction sequence.

7. Performance, reliability, and cost

A timeout is a maximum wait, not a delay that Puppeteer always adds. When the locator becomes ready promptly, the action can proceed without using the full limit. A larger timeout can make a run take longer when an action is stuck, so reserve long limits for controls with a real reason to load slowly.

For reliable automation, keep waits bounded, use selectors that identify the intended element, and set a longer limit only at the operation that needs it. If your script runs against a page you control, making the page expose a clear ready state can be more dependable than repeatedly raising timeouts. Puppeteer’s locator documentation describes the readiness checks and retries; it does not prescribe a universal timeout.

There is no separate Puppeteer charge for choosing a timeout. Your practical cost is the time and compute consumed by a browser process waiting on a stalled action. A finite limit helps cap that wait.

8. Or skip the browser setup

If your task is to capture a webpage image or PDF rather than interact with it, ScreenshotNeo provides a website screenshot API and MCP server for developers. A single GET request returns a PNG, JPEG, WebP, or PDF. For example, request a WebP screenshot of Stripe:

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

See the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Learn more at ScreenshotNeo.

9. FAQ

Is the timeout value in seconds?

No. Pass milliseconds: 3000 means 3 seconds.

Does setTimeout() change the original locator?

It returns a cloned locator configured with the timeout. Use the returned locator or chain the method directly into the action.

What timeout should I choose?

Choose a bounded value that matches the expected readiness time for the page. The documentation provides examples, not a universal recommended value.

No. Configure navigation timeouts separately from locator action timeouts.