Free tools Windows power users keep installed
One-click scans. No signup required.
A ChromeDriver timeout in continuous integration (CI) is a symptom, not a diagnosis. Find the command that timed out—starting a browser session, loading a page, running a script, or waiting for an element—then compare the CI browser, driver, account, launch options, and harness with the working local setup. The right fix depends on which stage failed.
Identify which timeout you are seeing
Selenium has separate timeout settings for page loads, script execution, and implicit element-location waits. An explicit wait is different: it repeatedly checks for a particular condition. A message that says only “timeout” is not enough to choose a fix; note the exception, the command that raised it, and the relevant log lines.
As an Amazon Associate I earn from qualifying purchases.
| Where the failure occurs | What to investigate first |
|---|---|
| Creating a WebDriver session or starting Chrome | Browser and driver paths and versions, launch arguments, execution account, and CI harness or service configuration. |
driver.get() or another navigation command |
The page-load strategy, whether the load event completes, and whether the page is stalled on resources the test does not need. |
| Executing a script | Whether the script itself is waiting too long and whether the script timeout is appropriate for that operation. |
| Finding or interacting with an element | Whether the application has reached the specific state needed for the next action, and whether the test uses an appropriate explicit wait. |
Selenium’s Browser Options documentation describes timeout settings, including new-session defaults of 30,000 ms for script execution and 300,000 ms for page loading. Those are configuration defaults, not guarantees for every binding or implementation; check the version and configuration actually used by your test.
Compare the CI runtime with the local runtime
Do not assume CI runs the same browser or driver as your development machine. Log the actual paths, versions, arguments, and execution context used by the failing job. Chrome and ChromeDriver are separate executables, and CI images or setup scripts can select different versions than a local shell.
#1 Best Overall
- Record the operating system and container image, if applicable, and the account running the test.
- Log the Chrome executable path and version, and the ChromeDriver path and version.
- Capture the browser options and command-line arguments, including whether Chrome is headless.
- Note whether the browser is launched directly by the test or through a CI service, wrapper, or other harness.
When Chrome is installed somewhere other than the default location, set the binary explicitly in the browser options for your Selenium binding. For release selection and Chrome for Testing availability, use the official Chrome for Testing availability dashboard and the ChromeDriver version-selection guidance. Recheck those resources when updating CI images; release details change.
Isolate browser startup failures
ChromeDriver’s official troubleshooting guidance specifically covers continuous build systems. If session creation fails, try launching the same Chrome binary with the same arguments directly under the CI execution account, where feasible. This separates a browser or environment startup problem from a WebDriver or harness problem.
- Reproduce outside WebDriver. Use the CI-selected Chrome binary and launch arguments under the same account. If Chrome fails there, inspect its installation and environment first.
- Compare with the harness. If Chrome launches directly but not through the job, investigate the CI service, wrapper, environment variables, permissions, and how it supplies options.
- Check the Linux account and sandbox. ChromeDriver notes that running Chrome as root on Linux is a common startup-crash cause. Run the browser as a regular user instead. Do not make
--no-sandboxa routine workaround: ChromeDriver describes it as unsupported and highly discouraged. - Verify both executables. Confirm the binary paths and versions in the failing job rather than relying on what is installed locally. Align the browser and driver using the current official release guidance.
ChromeDriver’s guidance, “Chrome doesn’t start or crashes immediately,” recommends checking the binary and arguments, launching Chrome directly, and reproducing outside the special harness. If the failure persists, retain the exact CI command, versions, arguments, and logs in a minimal reproducible case.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Diagnose navigation timeouts separately
By default, Selenium’s normal page-load strategy waits for the document’s load event and complete ready state. A navigation timeout can therefore happen even when the part of the page your test needs is already usable—for example, if nonessential assets keep loading.
Selenium supports alternative page-load strategies: eager returns when the document is interactive, while none does not wait for document readiness. These are synchronization choices, not universal speed fixes. If you use either, explicitly wait for the application condition required by the next step; do not assume the page is ready just because navigation returned. See Selenium’s page-load strategy options.
Wait for the application state, not an arbitrary delay
A completed document does not mean a JavaScript application has finished rendering or revealed the control your test needs. Choose an explicit wait that matches the next action—for example, presence when locating an element, visibility before reading it, or clickability before clicking. Selenium’s Waiting Strategies documentation explains these approaches and warns: “Do not mix implicit and explicit waits.” Combining them can make elapsed time unpredictable.
Keep the wait close to the condition that matters. A fixed sleep may waste time when the page is fast and still fail when it is slow; a condition-based wait ends when the required state appears or its timeout expires.
PC 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 & 11Outdated 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 matchTroubleshooting by symptom
| Symptom | Likely area to inspect | Next action |
|---|---|---|
| Session creation fails before the test reaches a page | Chrome startup, executable selection, permissions, account, or harness. | Log paths, versions, and arguments; launch Chrome directly under the CI account; compare the direct launch with the harness. |
| Chrome crashes immediately on Linux CI | Execution as root is a known common cause. | Run Chrome as a regular user. Avoid treating --no-sandbox as a standard fix. |
| Navigation command exceeds its page-load timeout | Default normal strategy waiting for the load event, or a navigation that never completes. | Inspect the page-load behavior. Consider eager or none only if the test adds a sufficient explicit readiness wait. |
| Navigation returns, but an element lookup or interaction times out | Application rendering or state synchronization. | Wait explicitly for the relevant element condition; avoid mixing implicit and explicit waits. |
| It works on a developer machine but fails in the job | Differences in binaries, versions, account, arguments, OS/container, or harness. | Compare recorded CI details with the local runtime and reproduce under the CI account. |
Or skip the browser setup
If your goal is a screenshot rather than an automated browser test, ScreenshotNeo provides a website screenshot API and MCP server. For example, make a single request:
Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
See the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000. Sign up for free.
FAQ
Is a longer timeout the right fix?
Only if the failing operation legitimately needs more time. First identify the command and timeout category; a longer limit will not fix a browser that cannot start or a wait for the wrong application condition.
Does a successful page load mean the page is ready for a test?
No. Document readiness and application readiness are different. Wait for the state your next test action requires.
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.
