iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A ChromeDriver timeout in continuous integration (CI) is a symptom, not a diagnosis. First identify whether Chrome fails to start, navigation takes too long, a script exceeds its timeout, or the test reaches an element before the page is ready. Then compare the CI browser, driver, user account, launch options, and harness with the local environment. Raising a timeout may help only after you know which operation is failing.
Identify which operation is timing out
“Timeout” can refer to several different Selenium behaviors. Read the exception and locate the command that failed before changing configuration. Selenium documents distinct page-load, script, and implicit element-location timeouts; explicit waits are a separate condition-polling approach. See Selenium’s browser options and timeout documentation.
- Session creation or Chrome startup: WebDriver cannot establish a session, or Chrome crashes before the test can use it.
- Navigation: a call such as
driver.get(url)does not finish within the page-load timeout. - Script execution: an asynchronous script does not complete within the script timeout.
- Element lookup or readiness: an element is not found within an implicit wait, or an explicit wait’s condition is not met in time.
Record the exception type, failing command, and surrounding CI log lines. A page-load timeout calls for a different investigation than a failed explicit wait or a Chrome process that never starts.
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 matchCompare the CI runtime with the local one
CI may use a different operating system or container image, account, browser binary, ChromeDriver binary, launch arguments, or service wrapper than the shell where the test works. ChromeDriver’s troubleshooting guidance specifically includes continuous build systems and recommends checking the browser binary and arguments. See ChromeDriver: “Chrome doesn’t start or crashes immediately”.
#1 Best Overall
Capture these details from the failing job rather than assuming it uses the same setup as your workstation:
- OS, container image, and execution account.
- The actual Chrome executable path and version.
- The actual ChromeDriver executable path and version.
- Headless or headed mode, all Chrome arguments, and any browser options.
- Whether a CI service, wrapper, or test harness launches or manages the process.
Chrome and ChromeDriver are separate executables. If Chrome is installed outside the default location, configure its path in the browser options for your Selenium binding. Check the paths and versions selected at runtime, not only what a package manager or local development environment says is installed. For current browser and driver availability, consult Chrome for Testing and the ChromeDriver version-selection guidance.
Check whether Chrome can start under the CI account
When the failure occurs at session creation, test the same Chrome binary with the same arguments under the same CI user, if the runner allows it. ChromeDriver recommends launching Chrome directly and reproducing the problem outside the special build environment. If Chrome fails outside WebDriver too, investigate the browser installation or runtime environment. If it starts there but fails through the harness, focus on the harness or service configuration.
On Linux, check whether the job runs as root. ChromeDriver identifies running Chrome as root as a common startup-crash cause. Run the browser as a regular user where possible. Do not make --no-sandbox a routine workaround: ChromeDriver describes it as unsupported and highly discouraged. See the Chrome startup troubleshooting guidance.
Choose navigation behavior deliberately
Selenium’s default page-load strategy, normal, waits for the document’s load event and complete ready state before navigation returns. That does not guarantee a JavaScript application has finished rendering or that the specific control your test needs is available. Conversely, long-running or nonessential assets may keep a navigation open even when the test could proceed.
Selenium also supports eager and none page-load strategies. Consider them only when the test follows navigation with a suitable readiness check. They change when navigation returns; they do not make an application ready by themselves. See Selenium browser options and Selenium waiting strategies.
Wait for the application’s actual readiness condition
If navigation returned but an element appears later, wait for the condition needed by the next action—for example, presence, visibility, or interactability. An explicit wait makes that condition part of the test rather than relying on a fixed delay that may be too short on a loaded runner and unnecessarily long locally.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesA language-neutral Selenium pattern is:
- Navigate to the page.
- Wait until the specific element or application state required by the test is satisfied.
- Perform the action only after that condition succeeds.
Use the wait API and condition appropriate to your Selenium language binding. Selenium warns: “Do not mix implicit and explicit waits.” Combining them can make actual elapsed time unpredictable because each element lookup inside an explicit wait may itself consume the implicit-wait interval. See Selenium: Waiting Strategies.
Best Value
Change the timeout only after locating the cause
Once you know which timeout applies, decide whether the configured limit is genuinely too short for the intended operation or whether the operation is stuck or poorly synchronized. Increasing a page-load timeout will not repair a Chrome startup crash; increasing an element wait will not fix a mismatched binary.
Selenium’s browser-options documentation gives numeric defaults for a new WebDriver session, including a 30,000 ms script timeout and a 300,000 ms page-load timeout. These are configuration defaults, not guarantees for every binding or implementation; verify the behavior for the Selenium version and driver in your CI job. See Selenium browser options.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Diagnose the failure in this order
- Capture the exact failure: save the exception, failing WebDriver command, timeout category, and relevant CI logs.
- Compare runtime details: log the CI OS or image, execution account, Chrome and ChromeDriver paths and versions, and all launch arguments.
- Reproduce Chrome startup directly: use the CI binary and arguments under the CI account where feasible, outside WebDriver and the harness.
- Correct account or sandbox setup: on Linux, use a regular user rather than relying on
--no-sandbox. - Align Chrome and ChromeDriver: confirm the job did not select versions different from the known working setup; use Chrome for Testing availability and version-selection resources when pinning or installing.
- For navigation failures, review page-load strategy: retain
normalunless the test has a deliberate reason to useeagerornoneand a readiness condition afterward. - For late elements, wait on the needed condition: use a targeted explicit wait and avoid mixing wait types.
- If the failure remains, preserve a reproducible case: include the CI command, runtime details, versions, arguments, and logs when asking for help or reporting an issue.
Common CI timeout symptoms and fixes
| Symptom | Likely area to investigate | First useful check |
|---|---|---|
| Session creation fails or Chrome exits immediately | Binary path, launch arguments, account, sandbox setup, or CI harness | Run the same Chrome binary and arguments directly as the CI user; compare logged paths and versions. |
get or navigation hits a page-load timeout |
Navigation strategy or a load event that takes too long | Check whether normal waiting is required; if changing strategy, add an explicit application-readiness wait. |
| Navigation succeeds but a later element wait expires | Application synchronization or an incorrect readiness condition | Wait for the specific element’s presence, visibility, or interactability needed by the next step. |
| Elapsed time does not match the explicit wait limit | Implicit and explicit waits being combined | Remove the mixed wait configuration and use one targeted synchronization strategy. |
| It works outside CI but fails in the job | Different image, user, binaries, options, or harness | Compare runtime logs and reproduce under the CI account outside the harness. |
Or skip the browser setup
For a screenshot rather than an interactive Selenium test, ScreenshotNeo provides a website screenshot API and MCP server. A single request can return an image or PDF; the API includes options for full-page capture, waiting for a selector or network idle, and custom headers or cookies. Its clean-shot behavior accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with response headers indicating the page verdict and billing status. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf.
Example cURL request (replace the target URL and supply your API key):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options and response details. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.
Quick Recap
What to include in a useful bug report
- The exact CI command and the failing WebDriver operation.
- The exception and a focused log excerpt showing the timeout or Chrome exit.
- CI OS or image, execution user, browser and driver paths and versions.
- Chrome arguments and whether the failure reproduces outside the harness.
- A minimal test case and the Selenium binding and version.
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.
