Use await page.waitForNetworkIdle() to wait for Puppeteer’s network-idle condition directly, or pass waitUntil: 'networkidle2' to page.goto() when the condition should be part of navigation. The direct method defaults to zero concurrent connections and a 500 ms quiet period; the navigation events networkidle0 and networkidle2 use their own documented thresholds. Network quiet is not proof that a particular application task is complete, so choose a targeted condition when your script depends on a specific element or state.
Wait for network idle directly
In Puppeteer v25.12.0, call page.waitForNetworkIdle() after opening the page or at another point in your workflow. It returns a Promise<void> that resolves when Puppeteer considers network activity idle.
await page.waitForNetworkIdle();The documented defaults are concurrency: 0 and idleTime: 500 milliseconds. The method always waits at least the configured idle time. For a page that needs a different threshold or quiet interval, pass options explicitly:
await page.waitForNetworkIdle({
concurrency: 2,
idleTime: 1_000,
timeout: 30_000,
});Here, concurrency is the maximum number of concurrent network connections treated as inactive, and idleTime is how long the network must remain quiet. These values are examples, not universal recommendations; set them to match the behavior your workflow needs.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
Wait for network idle during navigation
Use page.goto() with a lifecycle event when navigation should not finish until its network-idle condition is met:
await page.goto('https://example.com', {
waitUntil: 'networkidle2',
});Puppeteer’s screenshot guide uses this navigation pattern before taking a screenshot. The two lifecycle options differ by the number of connections allowed during the 500 ms idle interval:
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
| Option | Documented condition | Use when |
|---|---|---|
networkidle0 |
At most zero active connections for at least 500 ms | Navigation should wait for a completely quiet network under this lifecycle definition. |
networkidle2 |
At most two active connections for at least 500 ms | Navigation may proceed with up to two connections remaining; this is also the event used in Puppeteer’s screenshot example. |
These lifecycle events are navigation conditions. page.waitForNetworkIdle({ concurrency, idleTime }) is a separate direct wait with configurable options; do not assume that the APIs are interchangeable in every respect.
Choose a wait that matches the task
| Wait choice | What it observes | Best fit |
|---|---|---|
waitUntil: 'networkidle0' |
Navigation with no more than zero connections for the 500 ms interval | A navigation that requires a completely quiet network by this definition. |
waitUntil: 'networkidle2' |
Navigation with no more than two connections for the 500 ms interval | A navigation that can tolerate up to two connections remaining. |
page.waitForNetworkIdle(options) |
A direct, configurable network-idle wait | A wait separate from navigation or one needing a custom connection threshold or quiet interval. |
| A locator or app-specific condition | Whether an element or application state is ready | A task that depends on a particular visible, enabled, or otherwise ready UI state rather than general network activity. |
Network idle describes network activity, not application completeness. Background requests can prevent the condition from being reached, while a page can become quiet before the specific element or state your script needs is ready. When the outcome is an element or action, a locator or other application-specific wait expresses that requirement more directly. Puppeteer’s interaction guide describes locators as automatically waiting for elements and relevant action preconditions.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Rank #3
Set a timeout or cancel the wait
The direct wait options extend Puppeteer’s shared wait options. Those options document a default timeout of 30,000 ms; you can set a different timeout in the wait or change page timeout settings. Passing timeout: 0 disables the timeout. An AbortSignal can cancel a wait.
await page.waitForNetworkIdle({
concurrency: 2,
idleTime: 1_000,
timeout: 10_000,
});Choose a timeout appropriate to the workflow. Disabling it removes the time limit, so use that only when an indefinite wait is acceptable to your script.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Troubleshoot network-idle waits
- The wait times out. The page may not meet the selected threshold before the timeout. Consider whether persistent activity is expected, whether
networkidle0is stricter than the page permits, and whether a locator or application-specific condition better matches the task. - The wait resolves, but the target is not ready. Network quiet does not establish that a particular UI state has completed. Wait for the required element or state instead of treating network idle as a readiness guarantee.
- You are unsure whether to use the navigation event or direct method. Put
waitUntil: 'networkidle2'or'networkidle0'inpage.goto()when the condition belongs to navigation. Usepage.waitForNetworkIdle()separately when you need to tune the options or wait at another stage. - The script waits longer than expected. The direct method must wait at least its configured
idleTime. Review that value and the timeout setting; a quiet interval is a minimum condition, not a prediction of total wait duration.
Or skip the browser setup
If your goal is simply to capture a site, ScreenshotNeo provides a screenshot API that returns an image or PDF from one GET request. Its clean-shot options accept consent banners before capture and remove known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. An MCP server provides screenshot tools for AI agents, including Claude, Cursor, and other MCP clients.
Example cURL request (see the ScreenshotNeo API documentation):
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchescurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Learn about ScreenshotNeo or sign up free for 1,000 screenshots a month, with no card.
Frequently Asked Questions
How long does Puppeteer wait for network idle?
For the direct method, the documented default quiet interval is 500 ms, and the method waits at least the configured interval. The general wait-options reference documents a 30,000 ms default timeout.
What is the difference between networkidle0 and networkidle2?
For navigation lifecycle waits, networkidle0 permits at most zero connections and networkidle2 permits at most two, each for at least 500 ms.
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.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →
