Menu
Sign up

"Navigation timeout of 30000 ms exceeded" in Puppeteer: causes, reproduced, and fixes

Why page.goto throws "Navigation timeout of 30000 ms exceeded": four causes reproduced with Puppeteer 25.7 and Playwright 1.64, and the fixes we ran.

Published November 21, 2026 · 7 min read

"Navigation timeout of 30000 ms exceeded" is Puppeteer's way of saying that page.goto() waited its full 30 seconds for an event that never came. It rarely means the page did not load. It means one particular signal — by default the window's load event — never fired, and the reasons for that are few and easy to tell apart. This page reproduces each of them on a small test server, shows which waitUntil setting survives which one, and gives the fixes we ran.

How we tested. On 2026-11-21, Puppeteer 25.7.0 (Chrome for Testing 152) and Playwright 1.64.1 on Node.js 20, against a local Node server with four pages: /hang (the server accepts the connection and never answers), /slow-image (the content is there, but one <img> keeps downloading forever), /stream (the page opens a server-sent events connection, like a live chat or a dashboard) and /iframe (the page embeds an iframe from /hang). To keep the runs short we set timeout: 5000; the message is the same with the default, only the number changes. We did not test against remote sites, proxies or CI machines, where slower networks add to every number here.

The error

TimeoutError: Navigation timeout of 30000 ms exceeded
    at new Deferred (.../puppeteer-core/lib/puppeteer/util/Deferred.js:57:34)
    at new LifecycleWatcher (.../puppeteer-core/lib/puppeteer/cdp/LifecycleWatcher.js:70:46)
    at CdpFrame.goto (.../puppeteer-core/lib/puppeteer/cdp/Frame.js:152:29)

It comes from page.goto(), page.reload(), page.goBack() and page.waitForNavigation(). All of them wait for the lifecycle event in waitUntil (default load) and give up after timeout (default 30,000 ms), as the page.goto reference documents. Playwright says the same thing in fewer words:

page.goto: Timeout 30000ms exceeded.

What times out, and with which waitUntil

Every cell is one page.goto() with timeout: 5000:

Test page load domcontentloaded networkidle0 networkidle2
/slow-image: one image never finishes timed out 30 ms timed out 1,016 ms
/stream: an open EventSource 56 ms 59 ms timed out 529 ms
/iframe: an iframe whose server never answers timed out timed out 1,016 ms 1,013 ms
/hang: the server never answers timed out timed out timed out timed out

The same pages in Playwright 1.64.1:

Test page load domcontentloaded networkidle commit
/slow-image timed out 22 ms timed out 16 ms
/stream 30 ms 22 ms 520 ms 11 ms
/iframe timed out 27 ms timed out 21 ms

Three things in these tables are worth knowing before you change any code:

  • load waits for every subresource. One image, font or script that never finishes is enough to hold it forever. On real sites this is an ad, a tracking pixel or a third-party widget whose server is slow from where your script runs.
  • networkidle0 cannot finish on a page that keeps a connection open. Server-sent events, WebSockets, long polling and analytics beacons keep the count above zero. networkidle2 tolerates two open connections and finished.
  • In Puppeteer, domcontentloaded waits for iframes too. Its lifecycle watcher only reports a navigation done when every child frame that has started loading has reached the same event (checkLifecycle in LifecycleWatcher.ts walks frame.childFrames()). An embedded widget whose server hangs held domcontentloaded until the timeout. Playwright returned in 27 ms; its page.goto reference lists commit, domcontentloaded, load and networkidle, and discourages networkidle for testing.

Cause 1: the server never answers

/hang timed out with every setting, as it must: there is no page. On real jobs this is a host that is down, a firewall that drops packets, a site that blocks datacenter IPs by not answering, or a URL that only works inside your network (the "works on my laptop, times out in CI" case). Check it outside the browser first:

curl -s -o /dev/null -w "%{http_code} %{time_total}s\n" --max-time 20 https://example.com/

A curl that also hangs means no Puppeteer setting will help: fix the network, the proxy or the URL. A curl that returns quickly while Puppeteer times out points at causes 2–4.

Cause 2: one request never finishes

The page's content is there, but load (and networkidle0) wait for the last request. Two fixes, both run against /slow-image.

Wait for the content, not for the event.

await page.goto(url, { waitUntil: 'domcontentloaded' });
await page.waitForSelector('#ready', { timeout: 10_000 });

On /slow-image, domcontentloaded returned in 30 ms with the heading already in the page (and in 143 ms with the selector wait on /stream). It is the pattern we use ourselves: decide what "ready" means for this page — a heading, the chart, the price — and wait for that. Waiting for page load in Puppeteer measures what each waitUntil option catches on a real page.

Block the request that hangs.

await page.setRequestInterception(true);
page.on('request', (req) => {
  if (req.url().endsWith('/never.png')) return req.abort();
  req.continue();
});
await page.goto(url, { waitUntil: 'load' });   // 43 ms instead of a timeout

In practice you block by type or host — req.resourceType() === 'media', ad and analytics domains — which also makes screenshots faster (speeding up Puppeteer screenshots measures it).

Cause 3: networkidle0 on a page that never goes quiet

If you chose networkidle0 to be safe, it is the setting that times out on chat widgets, live dashboards and pages with an open WebSocket. Use networkidle2, or better, domcontentloaded plus waitForSelector as above.

Cause 4: an iframe that hangs (Puppeteer only)

Embedded videos, maps, chat and comment widgets are iframes. If one of their servers does not answer, Puppeteer's load and domcontentloaded both wait for it. Two ways out:

  • waitUntil: 'networkidle2' returned after 1,013 ms on our /iframe page.
  • Catch the timeout and carry on (next section) — the main document had loaded long before.

If you know which embed it is, abort its requests with request interception as in cause 2.

The page is usually fine after the timeout

A TimeoutError from page.goto() does not close or reset the page. After /slow-image timed out with load, the same page object still worked:

try {
  await page.goto(url, { waitUntil: 'load', timeout: 15_000 });
} catch (e) {
  if (e.name !== 'TimeoutError') throw e;
  // Navigation did not "finish", but the document is there:
}
const heading = await page.$eval('#ready', (el) => el.textContent); // "Content is here"
await page.screenshot({ path: 'page.png' });                        // 6,281 bytes

Check for the element you need before you trust the result: on /hang there is nothing to read, and the screenshot would be a blank page.

Raising or disabling the timeout

await page.goto(url, { timeout: 60_000 });   // this call
page.setDefaultNavigationTimeout(60_000);    // every navigation of this page
page.setDefaultTimeout(60_000);              // navigations and waitFor* calls

(setDefaultNavigationTimeout takes precedence over setDefaultTimeout for navigations.) setDefaultNavigationTimeout(2000) made /hang fail after 2,001 ms with "Navigation timeout of 2000 ms exceeded". A longer timeout helps only with a page that is slow but finishes. It does nothing for the four causes above except make each failure take longer.

timeout: 0 turns the limit off. On /hang, page.goto(url, { timeout: 0 }) was still pending after 8 seconds and would have waited forever, holding a browser tab and whatever job was waiting on it. Do not ship it; keep a finite timeout on every navigation and on every waitForSelector.

Checklist

  1. curl the URL from the same machine. No answer: a network problem, not a Puppeteer one.
  2. Note which waitUntil you use. load and networkidle0 are the two that hang on real pages.
  3. Switch to domcontentloaded + waitForSelector for the content you need.
  4. Still timing out in Puppeteer with domcontentloaded? Look for an iframe (document.querySelectorAll('iframe')); use networkidle2 or block it.
  5. Log e.name === 'TimeoutError' separately from other errors. A navigation that was aborted (net::ERR_ABORTED) or refused (net::ERR_CONNECTION_REFUSED) is a different problem. A context destroyed by a redirect is covered in execution context was destroyed; a browser that went away in Target closed.

When the job is just a screenshot

Our screenshot API makes the same trade-offs for you: it navigates with domcontentloaded, then waits for load for at most a few seconds, so a page with one endless ad request still gets captured. wait_for waits for a selector like the fix above, and a page that does not load in time ends with status: failed and the reason timeout instead of hanging. We have not measured it against every case on this page — a hanging iframe in particular still holds Puppeteer's domcontentloaded underneath — so test your own URLs; a failed capture returns its quota.

curl -X POST "https://shareglint.com/v1/screenshots?wait=true" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/", "wait_for": "#content"}'

A viewport screenshot is 1 render of the quota (pricing). The API takes public URLs only; for pages behind a login keep your own Puppeteer.

FAQ

What does "Navigation timeout of 30000 ms exceeded" mean?

page.goto (or reload, or waitForNavigation) waited 30,000 ms, its default, for the event named in waitUntil and the event never came. With the default waitUntil: 'load', one image, script or iframe that never finishes downloading is enough. The page itself has usually loaded: in our test its content could still be read and screenshotted after the error.

How do I fix the Puppeteer navigation timeout?

Wait for less, then for what you need: page.goto(url, { waitUntil: 'domcontentloaded' }) followed by page.waitForSelector('#content'). If one request hangs, block it with request interception. Raising the timeout only helps when the page is slow but does finish.

How do I change or disable the navigation timeout?

Per call: page.goto(url, { timeout: 60000 }). For every navigation of a page: page.setDefaultNavigationTimeout(60000). timeout: 0 disables it, and then a server that never answers makes page.goto wait forever; in our test it was still pending after 8 seconds with no end in sight.

Why does waitUntil networkidle0 time out?

networkidle0 waits for 500 ms with no open connection. A page with server-sent events, a WebSocket, long polling or a never-ending download never gets there. In our test networkidle0 timed out on a page with an EventSource, while networkidle2, which allows two open connections, finished in 529 ms.

Why does domcontentloaded still time out?

Puppeteer waits for the event in every child frame that has started loading, not just the main page. An iframe whose server never answers held domcontentloaded until the timeout in Puppeteer 25.7; Playwright 1.64 returned in 27 ms on the same page.

What is the Playwright version of this error?

"page.goto: Timeout 30000ms exceeded." Playwright has the same 30-second default and the same causes; its waitUntil values are load, domcontentloaded, networkidle and commit.