How to Set a Navigation Timeout in Puppeteer

Set a navigation timeout for every relevant navigation on a Puppeteer page with page.setDefaultNavigationTimeout(timeoutInMilliseconds). For one navigation only, pass timeout in that call’s options. Puppeteer measures both values in milliseconds: 60_000 is 60 seconds, and 0 disables the timeout.

page.setDefaultNavigationTimeout(60_000);
await page.goto('https://example.com');

The default wait timeout documented by Puppeteer is 30,000 milliseconds. A navigation-specific default is the right choice when you want to change navigation limits without changing the defaults for other page waits. [Puppeteer: Page.setDefaultNavigationTimeout()] [Puppeteer: WaitForOptions]

1. Choose the timeout scope

Need	Use	Applies to
One limit for navigation calls on this page	page.setDefaultNavigationTimeout(ms)	goBack(), goForward(), goto(), reload(), setContent(), and waitForNavigation()
A different limit for one operation	That operation’s timeout option	Only that call
A broader default for page waits	page.setDefaultTimeout(ms)	General page waits; use the navigation-specific method when you intend to change navigation limits

These settings are scoped to the page where you call them. Set the default after creating a page and before the operations that should use it. A per-call timeout is useful when one destination or navigation step has different timing needs.

2. Set a page-wide navigation timeout

Here is a complete runnable example. Install Puppeteer in a Node.js project with npm install puppeteer, save this as navigate.js, and run node navigate.js.

const puppeteer = require('puppeteer');

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

    // All applicable navigation operations on this page use a 60-second limit.
    page.setDefaultNavigationTimeout(60_000);

    await page.goto('https://example.com');
    console.log('Loaded:', page.url());
  } finally {
    await browser.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

The method takes a number of milliseconds. Pick a limit that gives the site enough time to complete the navigation while still allowing your program to recover from a page that never finishes. A larger limit does not resolve unrelated failures such as an invalid URL, SSL error, unreachable server, or main-resource failure. [Method reference] [Frame.goto() failure conditions]

3. Override the timeout for one navigation

Pass timeout to page.goto() to change the limit for that call without changing the page’s default:

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

The documented default for wait options is 30 seconds. Set timeout: 0 to disable the timeout for that call. Use this carefully: if the operation never completes, your code can wait indefinitely unless another limit or cancellation mechanism applies. [WaitForOptions]

waitUntil controls what Puppeteer waits for; it is separate from the timeout duration. For example, waiting for domcontentloaded can finish before a page’s later network activity has settled. Choose the completion condition that matches the task rather than increasing the timeout by default.

4. Set a general page wait timeout

page.setDefaultTimeout(ms) sets the broader default timeout used by page waits. When the problem is specifically that navigation calls need more or less time, prefer page.setDefaultNavigationTimeout(ms). If you configure both, keep their scopes in mind and use an explicit per-call timeout when one operation needs a clear exception. [Page.setDefaultTimeout()] [Page.setDefaultNavigationTimeout()]

5. cURL, Python, and ScreenshotNeo

Puppeteer’s navigation timeout is a setting in the browser automation code. cURL and Python requests do not use Puppeteer; their request timeout options concern the HTTP request. If you need a website screenshot without launching and configuring a browser yourself, ScreenshotNeo provides a screenshot API and MCP server. Its API accepts a URL in one GET request and returns an image or PDF. See the ScreenshotNeo website and the API documentation.

cURL

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

Python

import requests

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

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = Buffer.from(await res.arrayBuffer());
await require('node:fs/promises').writeFile('shot.webp', bytes);

Or skip the browser setup

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 and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response includes X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. 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.

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

See the ScreenshotNeo docs for request options. Create a free account for 1,000 screenshots a month, with no card.

6. Troubleshoot navigation timeouts

Symptom	Likely cause	What to do
Navigation times out at about 30 seconds	The call is using the documented default timeout.	Set a page-wide navigation timeout or pass a larger timeout to that call.
A longer timeout does not make navigation succeed	The failure may be an invalid URL, SSL error, unreachable server, or failed main resource rather than elapsed time.	Check the destination and connectivity, then inspect the original error. A timeout change only changes how long Puppeteer waits.
The wait is much longer than expected	The selected waitUntil condition may wait for activity beyond the page’s initial document load.	Use a completion condition that matches your task, such as domcontentloaded when the initial DOM is sufficient.
Non-navigation waits still time out	setDefaultNavigationTimeout() is scoped to navigation methods.	Configure the general page wait default with page.setDefaultTimeout(), or set an explicit timeout on the relevant wait.
The operation never returns after setting zero	timeout: 0 disables the timeout.	Use a finite timeout if the task needs a bounded wait, or arrange another way for your program to stop waiting.
The timeout setting seems ineffective	It may be applied to a different page or after the navigation call starts.	Set the default on the same Page before navigation, or pass the option directly to the call.

7. Performance, reliability, and cost

A timeout sets the maximum time an operation may wait; it does not make the server or page load faster. Excessively long limits can keep stalled jobs occupied, while limits that are too short can reject slow but successful navigations. Use the smallest limit that fits the task and handle timeout errors so a failed navigation does not silently halt the rest of a job.

Puppeteer itself has no per-navigation timeout charge described in these API references; infrastructure and browser runtime costs depend on how you run it. ScreenshotNeo bills only clean shots: bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Its listed monthly plans are Free (1,000 shots), Starter ($5 for 3,000), Growth ($15 for 15,000), Pro ($39 for 60,000), Scale ($99 for 250,000), and Business ($249 for 1,000,000); yearly billing gives two months free. Check the response’s billing and verdict headers when integrating it.

FAQ

Does the timeout value use seconds?

No. Puppeteer expects milliseconds: use 30_000 for 30 seconds.

Does a default navigation timeout affect every tab?

It is set on a Page instance. Apply it to each page that needs that setting.

Can I disable the timeout?

Yes. The wait options reference documents timeout: 0 as disabling the timeout. Remember that the operation may then wait indefinitely.

Which setting should I use for one slow URL?

Pass a larger timeout in that URL’s navigation call to avoid changing other navigation operations on the page.