There is no single “headless Chrome timeout.” Headless is only Chrome’s operating mode; the timeout is configured in the automation framework controlling it. Identify whether the failure is a navigation, element/action wait, JavaScript execution, test budget, or browser-session problem, then change that specific timeout. Navigation settings commonly override general page settings, and Selenium keeps script, page-load, and implicit-wait limits separate.
Choose the timeout that matches the failure
Read the exception and the operation that was running when it occurred. A timeout is a deadline for a framework condition, not proof that Chrome itself is frozen.
| Symptom | Setting to inspect | What it controls |
|---|---|---|
goto, reload, or URL navigation expires |
Navigation timeout | Waiting for the selected navigation event or condition |
| A locator, selector, click, or element wait expires | General/action timeout or per-call timeout | Finding an element or completing an interaction |
| JavaScript execution is interrupted | Script timeout (especially Selenium) | Time allowed for asynchronous script execution |
| The browser call succeeds but the test runner aborts | Test-level timeout | Total budget for the test, including browser operations |
| The process hangs after an operation | Session, process, or application lifecycle | Whether the browser and your code terminate cleanly |
Set a meaningful limit for the operation that is slow. Making every timeout unlimited can turn a broken page or dead connection into a build that never finishes.
Puppeteer: separate general waits from navigation
Puppeteer’s Page API exposes page-wide defaults. page.setDefaultTimeout() applies to methods that accept a timeout. page.setDefaultNavigationTimeout() applies to navigation-related methods such as goto, reload, and setContent. For navigation operations, the navigation setting takes precedence.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated 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 matchRunnable example
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage();
page.setDefaultTimeout(15_000); // selectors and actions
page.setDefaultNavigationTimeout(30_000); // URL navigations
await page.goto('https://example.com', {
waitUntil: 'domcontentloaded'
});
await page.locator('h1').wait();
await browser.close();The values above are examples, not universal recommendations. Choose them from the expected duration of the operation and the cost of waiting in your environment. Puppeteer documentation reports a 30-second default for selected wait methods and states that 0 disables the timeout for those waits; check the particular method because options and defaults differ.
Override one operation
await page.goto(url, {
waitUntil: 'load',
timeout: 45_000
});
await page.waitForSelector('.report-ready', {
timeout: 10_000
});A per-call value is useful when one known-slow report or download should not raise the limit for every page. Keep the navigation completion event appropriate to your goal: domcontentloaded means the initial HTML was parsed, while load waits for the page’s load event. Neither guarantees that a single-page application has finished rendering its data.
Playwright: page, context, navigation, and test budgets
Playwright provides defaults at page and browser-context level, navigation-specific defaults, and a per-operation timeout. Navigation timeouts take precedence over general operation defaults for navigation methods. The Page API describes 0 as no maximum for the relevant operation, so set deliberate bounds when you need failures to end predictably.
Set defaults and use a readiness assertion
import { chromium } from '@playwright/test';
const browser = await chromium.launch({ headless: true });
const context = await browser.newContext();
const page = await context.newPage();
page.setDefaultTimeout(10_000); // locators and actions
page.setDefaultNavigationTimeout(30_000); // navigations
await page.goto('https://example.com', {
waitUntil: 'domcontentloaded'
});
await page.getByRole('heading', { name: 'Example Domain' })
.waitFor({ state: 'visible' });
await browser.close();Navigation completion choices
Playwright supports commit, domcontentloaded, load, and networkidle. The choice is a contract about what your code needs:
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute- commit: the response has started and the document navigation has committed.
- domcontentloaded: the DOM is parsed; images and many subresources may still be loading.
- load: the page load event has fired.
- networkidle: no network connections for the required quiet period, which can be impossible on polling or streaming applications.
Playwright’s documentation says, “Don’t use this method for testing, rely on web assertions to assess readiness instead.” Use a locator assertion, a specific response, or an application-level ready marker rather than waiting for network silence.
await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
await expect(page.getByTestId('dashboard')).toBeVisible({ timeout: 15_000 });Do not confuse a test timeout with a page timeout
Playwright Test has its own test-level budget, documented in Test timeouts. A test can fail because the runner’s total deadline expired even when the page operation still had time remaining. Conversely, increasing the test budget does not change a navigation or locator timeout. Configure both only when the measured work requires it.
Selenium WebDriver: three independent timeout categories
Selenium’s Browser Options documentation distinguishes script execution, page loading, and implicit element-location waits. A new session is documented with a 30,000-millisecond script timeout and a 300,000-millisecond page-load timeout. These are documentation defaults; wrappers, language bindings, and future releases may differ, so verify the Selenium version you deploy.
Python example
from selenium import webdriver
from selenium.webdriver.common.by import By
options = webdriver.ChromeOptions()
options.add_argument('--headless=new')
driver = webdriver.Chrome(options=options)
# JavaScript execution, navigation, and implicit element lookup are separate.
driver.set_script_timeout(30)
driver.set_page_load_timeout(60)
driver.implicitly_wait(5)
driver.get('https://example.com')
heading = driver.find_element(By.TAG_NAME, 'h1')
print(heading.text)
driver.quit()Java example
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
WebDriver driver = new ChromeDriver(options);
Duration script = Duration.ofSeconds(30);
Duration pageLoad = Duration.ofSeconds(60);
Duration implicit = Duration.ofSeconds(5);
driver.manage().timeouts().scriptTimeout(script)
.pageLoadTimeout(pageLoad)
.implicitlyWait(implicit);
driver.get("https://example.com");
driver.quit();An implicit wait affects element-location calls; it does not extend a page-load timeout or a script timeout. Avoid mixing large implicit waits with explicit waits without understanding the compounded delay, because each lookup may consume the implicit interval.
Explicit waits for application readiness
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(20));
wait.until(ExpectedConditions.visibilityOfElementLocated(
By.cssSelector("[data-testid='ready']")
));Use an explicit condition that represents the state your next action needs. A completed page-load event only says the browser met Selenium’s selected navigation condition; it does not prove that an API call, hydration step, or client-side route finished.
Scope, precedence, and completion conditions
When documenting or reviewing a timeout, record five facts:
- Framework and version: Puppeteer, Playwright, or Selenium APIs and defaults can change.
- Scope: per call, page, browser context/session, or test runner.
- Operation: navigation, action/element wait, or script execution.
- Precedence: a per-call value normally wins; navigation-specific defaults override general page defaults for navigation.
- Completion condition: the event or assertion that defines success.
This record prevents a common mistake: raising a page timeout when the failing limit belongs to the test runner, or waiting for networkidle when the application intentionally maintains an open connection.
How to choose a useful value
Measure the normal path
Collect navigation, API, and rendering durations in the same region, CI environment, and device profile where the automation runs. Set the timeout above normal variance but below the point where a stuck job harms the pipeline. A single slow third-party resource may justify blocking that resource or waiting for your own readiness marker rather than doubling every deadline.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Use staged deadlines
Give navigation a bounded limit, then give the specific readiness assertion its own limit. This tells you whether the document failed to load or the application failed to become usable. Log the URL, selected event, timeout value, elapsed time, and the last observed state when a deadline expires.
Keep retries intentional
A retry can recover from transient DNS or infrastructure problems, but it should not conceal a deterministic selector or application defect. Cap retries and preserve the original timeout error in your report.
Troubleshooting timeout errors
Navigation times out although the page appears in a normal browser
- Check whether headless mode receives different redirects, authentication, geolocation, or user-agent behavior.
- Try
domcontentloadedinstead ofnetworkidleand then assert the exact ready element. - Inspect blocked requests, proxy settings, DNS, TLS, and server-side bot checks.
- Raise only the navigation timeout if measurements show a legitimate slow response.
The selector timeout is unchanged after increasing navigation timeout
These are different operations. Set Puppeteer’s default timeout or Playwright’s page/context default, or pass timeout on the locator/action. In Selenium, use an explicit wait or adjust the implicit wait; page-load settings do not apply.
Playwright reports a test timeout
Inspect the test-runner budget in addition to page defaults. A test-level deadline can terminate a sequence while an individual action still has time remaining. Reduce unnecessary waits, use a targeted assertion, or increase the test budget only when the full scenario genuinely needs it.
Selenium’s script throws a timeout
Configure set_script_timeout (or the equivalent binding API). Page-load and implicit waits do not extend asynchronous JavaScript execution.
The browser hangs forever
Look for a zero or otherwise unbounded timeout, an unresolved promise, a page that continually opens connections, or code that never closes the browser. Add a process-level watchdog, close the session in a finally block, and capture diagnostics before terminating it.
Increasing timeouts makes CI slower
Long limits increase the worst-case cost of every failure. Prefer a fast navigation condition plus a meaningful readiness assertion, and fail with context. Use separate limits for known slow operations rather than a global maximum that applies everywhere.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is a reliable screenshot rather than browser automation, ScreenshotNeo provides a one-call website screenshot API and MCP server. It accepts consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and whether it was billed. Its MCP tools—take_screenshot, get_page_info, and capture_pdf—work with Claude, Cursor, and other MCP clients.
See the complete parameter reference in the ScreenshotNeo documentation. 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}`);Every plan includes the features, including full-page and element capture, device and retina controls, PDF output, custom CSS and JavaScript, waits, request blocking, headers and cookies, geolocation, caching, signed links, webhooks, bulk capture, and a usage API. The Free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
FAQ
Does headless Chrome have a command-line timeout flag?
Not as a universal setting for page operations. The controlling framework owns navigation, action, script, and test deadlines.
Should I set every timeout to unlimited?
No. An unlimited wait can hide outages and leave workers stuck. Bound each operation and define what “ready” means for the page.
Free tools Windows power users keep installed
One-click scans. No signup required.
Why did page load finish before my app was usable?
Page-load completion covers a browser event selected by the framework. Client-side rendering, API calls, and hydration can continue; wait for an application-specific assertion.
Which Selenium timeout controls an element search?
The implicit wait affects element-location calls. Explicit waits provide more precise, condition-based control and do not replace script or page-load settings.
Frequently Asked Questions
Can one timeout setting control Puppeteer, Playwright, and Selenium?
No. Each framework defines its own names, scopes, defaults, and precedence rules; configure the API for the framework actually creating the browser session.
What is the safest first change when navigation is slow?
Confirm the selected navigation event, measure the real delay, and set a bounded navigation timeout. Then wait for a specific ready state instead of making all waits unlimited.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →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.
