"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:
loadwaits 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.networkidle0cannot finish on a page that keeps a connection open. Server-sent events, WebSockets, long polling and analytics beacons keep the count above zero.networkidle2tolerates two open connections and finished.- In Puppeteer,
domcontentloadedwaits for iframes too. Its lifecycle watcher only reports a navigation done when every child frame that has started loading has reached the same event (checkLifecycleinLifecycleWatcher.tswalksframe.childFrames()). An embedded widget whose server hangs helddomcontentloadeduntil the timeout. Playwright returned in 27 ms; itspage.gotoreference listscommit,domcontentloaded,loadandnetworkidle, and discouragesnetworkidlefor 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/iframepage.- 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
curlthe URL from the same machine. No answer: a network problem, not a Puppeteer one.- Note which
waitUntilyou use.loadandnetworkidle0are the two that hang on real pages. - Switch to
domcontentloaded+waitForSelectorfor the content you need. - Still timing out in Puppeteer with
domcontentloaded? Look for an iframe (document.querySelectorAll('iframe')); usenetworkidle2or block it. - 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.