Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteYes, you can often read a page after page.goto() times out. Catch the navigation error, call await page.content(), and then verify that the HTML contains the element or marker your job requires. A timeout only says that the selected navigation wait did not finish in time; it does not prove that the DOM is empty or complete. If the page, frame, or browser is no longer usable, extraction can still fail, so treat the returned HTML as an untrusted partial result until it passes an application-specific check.
The safe recovery pattern
This pattern keeps the navigation failure visible while attempting to read the current document:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
const page = await browser.newPage();
const url = 'https://example.com';
let navigationError;
try {
await page.goto(url, {
waitUntil: 'domcontentloaded',
timeout: 15_000,
});
} catch (error) {
navigationError = error;
// Continue only when your application permits partial results.
}
try {
const html = await page.content();
const containsExpectedContent = html.includes('expected marker');
if (!containsExpectedContent) {
throw new Error(
`Required content was not present after navigation${navigationError ? `: ${navigationError.message}` : ''}`,
);
}
console.log(html);
} finally {
await browser.close();
}page.content() returns a promise for the full HTML contents, including the DOCTYPE, according to the Puppeteer Page.content() reference. It is a separate operation from navigation. The catch block therefore records why navigation ended while the content call asks the page for its current HTML snapshot.
What a navigation timeout actually means
page.goto() waits for the condition you selected, such as domcontentloaded, load, or networkidle0. If that condition is not reached before the timeout, Puppeteer rejects the navigation promise. The distinction matters:
#1 Best Overall
- A timeout does not establish that there is no usable DOM.
- A timeout does not establish that the intended application data has loaded.
- A successful
page.content()call does not establish that the page is complete or correct. - If navigation is still changing the frame, or the page/browser has become unusable, the content call may fail; the API documentation does not promise recovery in those states.
In headless-shell scenarios, Page.goto() can resolve for valid HTTP error responses such as 404 or 500. Keep the response object and inspect its status instead of treating a resolved promise as proof of a successful page. See the Page.goto() documentation.
Choose the right readiness condition
Use a navigation event for basic document availability
domcontentloaded is useful when you need the parsed document quickly and can tolerate JavaScript-rendered content arriving later. load waits for the load event, including page resources. networkidle0 or networkidle2 can be appropriate for applications that finish through network requests, but analytics, polling, websockets, or ads may prevent an idle condition from occurring.
await page.goto(url, {
waitUntil: 'domcontentloaded',
timeout: 15_000,
});Changing from networkidle0 to domcontentloaded may avoid an unnecessary timeout, but it also means you must add a readiness check for the content you actually need.
Wait for the application’s content, not an arbitrary delay
After navigation, wait for a required selector or a function that expresses the data requirement:
Rank #2
await page.waitForSelector('article h1', { timeout: 10_000 });
const html = await page.content();await page.waitForFunction(() => {
const paragraphs = document.querySelectorAll('article p');
return paragraphs.length >= 3;
}, { timeout: 10_000 });
const text = await page.$eval('article', element => element.textContent?.trim() ?? '');The Puppeteer page-interactions guide documents selector and function-based waiting. A fixed setTimeout delay is only justified when the requirement is genuinely time-based; elapsed time alone is not evidence that the page is ready.
Validate partial HTML before accepting it
Define what “good enough” means for your job. A scraper might require a product ID, while a monitoring task might require a heading and a timestamp. Check both the marker and, when available, the HTTP response:
let response;
let navigationError;
try {
response = await page.goto(url, {
waitUntil: 'domcontentloaded',
timeout: 15_000,
});
} catch (error) {
navigationError = error;
}
const html = await page.content();
const title = await page.title();
const status = response?.status();
const usable = html.includes('<article') && html.includes('data-record-id');
if (!usable) {
throw new Error(JSON.stringify({
message: 'Required page content is missing',
navigationError: navigationError?.message,
status,
title,
}));
}For a targeted value, extract only that value after its selector is present. This avoids processing a large HTML string when the job needs one field:
await page.waitForSelector('[data-price]', { timeout: 10_000 });
const price = await page.$eval('[data-price]', element => element.textContent?.trim());Set timeouts narrowly
Per-navigation timeout
Prefer a per-call value when one slow destination needs a different policy:
Recommended Free Tools
await page.goto(url, {
waitUntil: 'domcontentloaded',
timeout: 30_000,
});Page-wide default
page.setDefaultNavigationTimeout(ms) changes the default maximum for goto, reload, setContent, waitForNavigation, goBack, and goForward. The API reference documents that scope.
page.setDefaultNavigationTimeout(30_000);Raising a limit helps only when the operation legitimately needs more time. It cannot fix a selector that never appears, a page that continuously polls, a blocked request, or an incorrect waitUntil choice. Keep selector waits separate from navigation waits so each failure identifies the missing condition.
Prevent click-and-navigation races
If a click starts navigation, begin the navigation wait before (and together with) the click. Puppeteer warns that awaiting the click first and registering waitForNavigation() afterward can miss the event:
const [response] = await Promise.all([
page.waitForNavigation({
waitUntil: 'domcontentloaded',
timeout: 15_000,
}),
page.click('a.next'),
]);
const html = await page.content();See the Puppeteer Page class documentation for the documented race condition. If the click updates the current document without a navigation, use a selector or function wait instead of waitForNavigation().
A diagnostic sequence for timeout failures
- Identify the rejected operation. A timeout from
goto(),waitForNavigation(),waitForSelector(), and a custom function wait has a different meaning. - Record the navigation error and response status. A timeout and an HTTP 404 are different failures and should be logged separately.
- Decide whether partial output is acceptable. If completeness is mandatory, do not silently publish the HTML returned after a timeout.
- Read the snapshot. Call
page.content()only while the page remains usable. - Check an application-specific marker. Verify a selector, attribute, text pattern, or data value required by the task.
- Retry with a bounded policy if appropriate. Use a small number of attempts and preserve the original error; retries do not repair a permanently missing selector.
- Save diagnostics on failure. Store the URL, wait condition, timeout, response status, page title, and a short HTML sample or screenshot where permitted.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
page.content() throws after the timeout |
The frame changed, navigation is still active, or the page/browser closed | Check the original error, ensure the page remains open, and retry the whole navigation in a fresh page when partial recovery is not safe. |
| HTML exists but expected text is absent | Client-side rendering has not finished, or the response is an error/consent page | Wait for the required selector or function; inspect status and title; reject the snapshot if the marker is missing. |
networkidle0 always times out |
Polling, analytics, websockets, or another long-lived request | Use domcontentloaded or load, then wait for a task-specific selector. |
| Navigation resolves with an error page | HTTP 404/500 can still produce a resolved navigation | Inspect response.status() and apply your own status policy. |
| Click result is inconsistent | click() and waitForNavigation() were awaited sequentially |
Start both promises in Promise.all(). |
| Increasing the timeout changes nothing | The readiness condition is wrong or the required element never appears | Replace arbitrary waiting with a selector/function tied to the actual data. |
Performance and reliability considerations
- Capture only what you need. Use
$evalfor one value instead of serializing the full document when HTML is unnecessary. - Keep timeout budgets explicit. Separate navigation, selector, and retry budgets so one slow page cannot consume an unbounded worker slot.
- Reuse browsers carefully. Reusing a browser is efficient, but create a fresh page after a suspected broken frame or contaminated session.
- Log readiness evidence. Record the wait condition and marker that passed; this makes partial-result bugs diagnosable.
- Treat retries as load. A retry can duplicate requests or trigger rate limits. Retry only transient failures and add backoff.
- Do not equate HTML with visual completeness. Images, fonts, and layout may still be loading even when the DOM contains the expected nodes.
Or skip the browser setup
If your goal is a clean screenshot or PDF rather than Puppeteer-level DOM control, ScreenshotNeo accepts one GET request for a URL. It can wait for a selector, delay, or network idle; run custom JavaScript; load lazy images; block requests; set headers, cookies, user agents, timezone, and geolocation; capture a CSS-selected element; and return PNG, JPEG, WebP, or PDF. Its cleanup step accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture.
Only clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response reports the result through X-Page-Verdict and X-Billed headers. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
See the ScreenshotNeo API documentation for the complete option list.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11When to reject the result
Reject the snapshot rather than guessing when the required marker is absent, the status is unacceptable, the page shows a bot challenge, or the browser reports a detached frame or closed target. A timeout is a signal to apply policy, not permission to publish whatever HTML happens to be available.
Best Value
- Used Book in Good Condition
Frequently Asked Questions
Does page.content() wait for navigation to finish?
No. It reads the current document snapshot. Add your own selector or function wait when content is rendered after navigation.
Should I use timeout: 0 to avoid failures?
No. An unlimited wait can consume workers indefinitely. Use a bounded timeout and an explicit retry or rejection policy.
Can a timeout return a 404 page?
Yes. A resolved navigation can still represent an HTTP error status, so inspect response.status().
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
