Selenium chromedriver version mismatch: Causes and Fixes

TL;DR

A selenium chromedriver version mismatch occurs when the ChromeDriver executable that starts the session does not support the Chrome binary it launches. Remove forced stale paths, let a maintained Selenium Manager resolve the local driver, or install a correspondingly versioned Chrome for Testing browser and driver pair together. Verify paths and versions in the exact CI worker or Grid node.

Key Takeaways

• Read the complete new-session error and record the browser and driver versions it names.
• Verify executable paths because PATH, system properties, caches, wrappers, and Grid nodes can override intended binaries.
• Use a maintained Selenium 4 release and Selenium Manager for ordinary local driver resolution.
• For reproducible CI, install Chrome for Testing and its correspondingly versioned ChromeDriver as one immutable pair.
• Do not disable ChromeDriver's compatibility check or solve mismatch with browser flags.
• Build and validate browser pairs in a controlled image pipeline instead of allowing surprise updates during a test run.
• On Selenium Grid, inspect the node's actual capabilities and binaries, not the test client's machine.

A selenium chromedriver version mismatch prevents ChromeDriver from creating a reliable WebDriver session with the Chrome binary it found. The error usually names the Chrome version that the driver supports and the current browser version. Fix it by discovering the actual executables in use, removing stale overrides, and resolving Chrome plus ChromeDriver as one compatible pair.

Modern Selenium 4 includes Selenium Manager for ordinary local driver and browser management, while Chrome for Testing publishes versioned Chrome and ChromeDriver assets together. Manual copying is now a specialized path, not the default. This guide covers local machines, hermetic CI, offline environments, Docker, Selenium Grid, update races, caches, and verification code without recommending unsafe compatibility bypasses.

TL;DR

Never use webdriver.chrome.disableBuildCheck as a fix. It suppresses the early guard without making an incompatible protocol implementation reliable.

1. Selenium chromedriver version mismatch: Recognize the Error

A genuine mismatch is normally a new-session failure. It occurs while constructing ChromeDriver or RemoteWebDriver, before the test can navigate. The most useful message resembles: this ChromeDriver version supports one Chrome version, while the current browser version is another. Preserve the actual numbers from your run rather than copying an example from a search result.

The exception type is commonly SessionNotCreatedException, a subtype of WebDriverException. Save the entire stack trace and Selenium's build and system information. A separate chrome not reachable or DevToolsActivePort startup message can have other causes, including profile, sandbox, permission, or resource failures. The Chrome not reachable diagnosis guide covers that path.

Record these facts before changing the machine:

exception type and full message
Chrome version reported by the error
ChromeDriver version reported by the error
Chrome binary path from verbose driver logs
ChromeDriver executable path
Selenium library version
worker, image, or Grid node identity
PATH and explicit driver configuration source

A test framework may catch WebDriverException and replace it with a generic setup failure. Preserve the cause. Otherwise, teams spend hours changing application waits for a browser session that never existed. Fail the environment check clearly and avoid retrying a deterministic mismatch.

2. Understand Chrome, ChromeDriver, and Selenium Responsibilities

Chrome renders and executes the application. ChromeDriver implements the WebDriver server for Chrome and communicates with the browser. Selenium's language binding sends W3C WebDriver commands and, for local sessions, Selenium Manager can discover and manage required binaries. These are related components with separate release and cache lifecycles.

ChromeDriver compatibility is not the same as the Selenium Java dependency version. Upgrading Selenium can provide a newer Selenium Manager and current client behavior, but it does not magically replace a driver path that your framework explicitly forces. Upgrading Chrome alone can leave an older cached driver behind. Updating only ChromeDriver can make it too new for a pinned older Chrome.

Since Chrome milestone 115, ChromeDriver releases are integrated with Chrome for Testing. Available CfT releases provide correspondingly versioned browser and driver downloads by channel and platform. For the most deterministic setup, choose one published CfT version and install both assets from that version.

For a normal workstation with installed Chrome, Selenium Manager can detect the browser and resolve a compatible driver when no driver executable is supplied. Its ability to download depends on network, proxy, cache, and security policy. In controlled CI, many teams instead build the pair into an image so test execution does not change infrastructure.

The compatibility check protects you. Do not disable it, and do not add Chrome arguments such as --no-sandbox or --disable-dev-shm-usage to address a version error. Those flags affect different concerns.

3. Verify the Executables Actually Used

The browser and driver you installed may not be the ones Selenium launches. Shell PATH order, webdriver.chrome.driver, the SE_CHROMEDRIVER environment variable, an IDE run configuration, a framework wrapper, an old WebDriverManager setup, or a Grid node can select another binary. ChromeDriver verbose logging shows the Chrome binary selected for the session.

Run version and path commands inside the exact failing worker:

set -eu
command -v chromedriver || true
chromedriver --version || true
command -v google-chrome || command -v google-chrome-stable || command -v chromium || true
google-chrome --version 2>/dev/null \
  || google-chrome-stable --version 2>/dev/null \
  || chromium --version 2>/dev/null \
  || true
printf 'webdriver.chrome.driver=%s\n' "${WEBDRIVER_CHROME_DRIVER:-not-a-shell-variable}"

The final line is only a reminder that a Java system property is not automatically a shell environment variable. Print system properties through safe application diagnostics or the build command, and do not expose secrets from unrelated Java options.

On Windows, use where chromedriver to list every PATH match. On macOS, inspect the executable inside the Chrome application bundle, not just the app directory. In Docker, execute diagnostics inside the built image. On Grid, execute them on the node, not on the client that sends RemoteWebDriver commands.

Delete or rename nothing until you know which configuration owns it. A stale binary might be required by another legacy job. Correct the scoped pipeline or image and document the migration.

4. Use Selenium Manager for Ordinary Local Sessions

With a maintained Selenium 4 release, the simplest local Java code is also the correct starting point:

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

ChromeOptions options = new ChromeOptions();
WebDriver driver = new ChromeDriver(options);
try {
    driver.get("data:text/html,<title>compatible</title>");
    System.out.println(driver.getTitle());
} finally {
    driver.quit();
}

When no driver location is forced, Selenium Manager can discover Chrome, resolve a compatible ChromeDriver, and cache the result. Remove obsolete setup such as a hard-coded System.setProperty("webdriver.chrome.driver", ...) unless you deliberately own manual driver selection. Search build plugins, test base classes, shell scripts, and environment variables, not just the failing test.

To request a Selenium-managed Chrome for Testing channel where your environment permits automated browser management, Selenium's options API supports browser version labels:

ChromeOptions options = new ChromeOptions();
options.setBrowserVersion("stable");
WebDriver driver = new ChromeDriver(options);

This is useful for an explicit managed channel, but CI should still control when caches change. Proxy, firewall, certificate, and offline policies can block resolution. Capture Selenium Manager diagnostics through your standard logging and approve download sources.

Do not combine Selenium Manager with a second automatic driver manager unless the precedence is intentional. Two caches and resolution rules make the selected executable difficult to predict.

5. Install a Matched Chrome for Testing Pair

Chrome for Testing provides versioned Chrome and ChromeDriver assets for supported platforms and release channels. Selecting both URLs from the same published version removes the desktop browser's silent auto-update from the equation. Use the official JSON endpoints in a controlled image-build or dependency-resolution job.

This shell fragment prints the Linux stable URLs from the official last-known-good metadata. It requires curl and jq:

set -euo pipefail
metadata=https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json
json=$(curl --fail --silent --show-error --location "$metadata")
version=$(jq -r '.channels.Stable.version' <<<"$json")
chrome_url=$(jq -r '.channels.Stable.downloads.chrome[] | select(.platform == "linux64") | .url' <<<"$json")
driver_url=$(jq -r '.channels.Stable.downloads.chromedriver[] | select(.platform == "linux64") | .url' <<<"$json")
printf 'version=%s\nchrome=%s\nchromedriver=%s\n' \
  "$version" "$chrome_url" "$driver_url"

A production resolver should fail if a value is empty, restrict allowed domains, use a trusted certificate path, archive the metadata used, scan downloaded artifacts according to policy, and publish them to an approved internal mirror. Build output should record version and provenance without secrets.

For a specific version, use the Chrome for Testing known-good versions metadata rather than taking whichever stable version exists during every test run. Promote an exact pair after smoke and regression validation. A channel label is convenient for discovery, but an immutable version is better for reproducibility.

Do not mix a CfT Chrome from one version with the driver URL from another metadata snapshot. Resolve and publish them as one unit.

6. Configure a Manually Managed Pair in Java

Manual paths are appropriate for offline agents, approved internal mirrors, custom image layouts, and deliberate browser matrices. Keep paths outside source code and validate both files before session creation. Selenium's current Java API accepts a Chrome binary through ChromeOptions and a driver executable through ChromeDriverService.Builder.

import java.nio.file.Files;
import java.nio.file.Path;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeDriverService;
import org.openqa.selenium.chrome.ChromeOptions;

Path chrome = Path.of(requireEnv("CHROME_BINARY")).toAbsolutePath();
Path chromedriver = Path.of(requireEnv("CHROMEDRIVER_BINARY")).toAbsolutePath();
if (!Files.isExecutable(chrome) || !Files.isExecutable(chromedriver)) {
    throw new IllegalStateException("Chrome pair is missing or not executable");
}

ChromeOptions options = new ChromeOptions();
options.setBinary(chrome.toString());
ChromeDriverService service = new ChromeDriverService.Builder()
        .usingDriverExecutable(chromedriver.toFile())
        .usingAnyFreePort()
        .build();
WebDriver driver = new ChromeDriver(service, options);

static String requireEnv(String name) {
    String value = System.getenv(name);
    if (value == null || value.isBlank()) {
        throw new IllegalStateException("Missing required environment variable: " + name);
    }
    return value;
}

The snippet is version-agnostic because the image or provisioning step owns compatibility. Add a build-time check that executes each binary with --version and a runtime smoke session. Do not infer compatibility merely because filenames contain similar numbers.

Protect environment variables from untrusted modification in shared runners. A binary path is executable configuration. Restrict file ownership and ensure the test user cannot replace an approved driver with an arbitrary program.

Manual management increases responsibility for updates, vulnerability response, platform architecture, executable permissions, and cleanup of old assets. Use it because reproducibility or policy requires it, not because it was common in Selenium 3 tutorials.

7. Clear Stale Overrides and Caches Safely

A mismatch that persists after an update often comes from precedence rather than download failure. Search the repository and pipeline for webdriver.chrome.driver, SE_CHROMEDRIVER, usingDriverExecutable, old WebDriverManager calls, copied driver folders, and PATH mutations. Inspect IDE configurations and reusable CI templates.

Selenium Manager maintains a cache. Other driver managers and browser tools use their own caches. Do not delete every user cache directory on a shared worker. First capture diagnostics, identify the resolver and exact stale entry, and remove only the owned scoped cache or rebuild the disposable worker image.

A clean diagnostic sequence is:

1. Print actual executable paths and versions in the failing worker.
2. Remove the explicit driver override from one isolated reproduction.
3. Run a minimal new ChromeDriver() health test.
4. Compare Selenium Manager logs and resolved paths.
5. Rebuild the worker from its declared image or provisioning source.
6. Fix the source configuration, not just the running machine.

Do not silently fall back to a developer's global PATH in CI. The job should either use Selenium Manager under an approved policy or reference image-owned paths. Fail early if the resolved pair differs from the image manifest.

Cache keys must include platform and architecture, plus the selected browser or driver version. A cache produced on macOS ARM cannot supply a Linux x64 binary. A key named only chromedriver-latest invites update races and provides poor auditability.

8. Prevent Auto-Update Races on Workstations and CI

Consumer Chrome can update independently of a pinned driver. The next test run then fails even though no repository commit changed. Selenium Manager reduces that risk by resolving against the discovered browser, but forced paths and restricted networks can still leave the old driver.

Choose an explicit update model per environment:

Do not disable updates indefinitely. Browsers carry security fixes, and automation should validate supported customer versions. Separate update intake from test execution: a scheduled pipeline discovers a candidate pair, scans and builds it, runs browser smoke and critical regression, then promotes an immutable image. Roll back by image identifier if evidence shows a regression.

Record the pair in test metadata. A report that says only Chrome cannot reproduce a browser-specific failure. Include full browser version, driver version when available, Selenium version, platform, and image digest. Avoid inventing a universal update frequency. Base cadence on security policy, supported-user channels, and release risk.

9. Build Reproducible Docker and Offline Environments

A Dockerfile should install the browser and driver pair in the same build stage or consume an approved base image that already owns them. Avoid curl latest during every test container startup. Runtime downloads add network dependence and can produce different binaries for two jobs using the same test commit.

For an offline environment, resolve artifacts in a connected controlled pipeline, verify and scan them, publish to an internal repository, then build the offline image from exact immutable inputs. Configure Java tests with image-owned paths or allow Selenium Manager to discover the installed pair without needing the network.

Add a build health check:

set -euo pipefail
/path/to/chrome --version
/path/to/chromedriver --version
test -x /path/to/chrome
test -x /path/to/chromedriver

Add a runtime WebDriver smoke test because two version strings do not prove that libraries, sandbox, permissions, profile directories, and DevTools startup work. Use a local data URL so the health check does not depend on the application or internet.

Multi-architecture images need platform-specific CfT assets. Select linux64, mac-arm64, mac-x64, win32, or win64 according to the published platform and your actual environment. Do not use an x64 driver through accidental emulation unless that configuration is intentionally supported and tested.

Keep browser layers cacheable, but invalidate them by exact pair version. Retain the previous approved image for controlled rollback and remove obsolete images according to storage and vulnerability policy.

10. Diagnose Version Mismatch on Selenium Grid

RemoteWebDriver does not use the ChromeDriver installed on the test client. The Grid node or cloud provider creates the browser session. Therefore, running chromedriver --version on the client can be completely irrelevant. Capture the failed new-session response and identify the node image or provider capability selection.

Request capabilities through browser options:

import java.net.URI;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;

ChromeOptions options = new ChromeOptions();
options.setBrowserVersion(System.getProperty("browserVersion", "stable"));
WebDriver driver = new RemoteWebDriver(
        URI.create(System.getenv("SELENIUM_GRID_URL")).toURL(),
        options);

A browserVersion request does not install a browser on a normal Grid node. The Grid must have a matching stereotype and compatible node image, or a provider must support that requested label. Inspect Grid node logs and returned capabilities. Avoid vendor-specific capability keys unless they are documented and namespaced.

Mixed node images can make mismatch intermittent. One node has the updated browser and driver, another has only one updated component. Trend session-creation failures by node, drain inconsistent nodes, and redeploy from the same immutable image. Do not retry until a compatible node is found while leaving the broken node in service.

For a cloud service, record provider session ID and requested sanitized capabilities, then use provider diagnostics. The service owns driver pairing, but your requested version may be unavailable or mistyped.

11. Validate the Fix With Capabilities and a Smoke Test

After session creation succeeds, record the actual capabilities and perform a small command sequence. Do not stop at the absence of a mismatch message. Confirm navigation, element lookup, script execution when used by the suite, window management, and teardown on the supported environment.

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;

import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;
import org.openqa.selenium.Capabilities;
import org.openqa.selenium.HasCapabilities;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

class ChromePairSmokeTest {
    @Test
    void reportsAndUsesResolvedBrowser() {
        WebDriver driver = new ChromeDriver();
        try {
            Capabilities capabilities = ((HasCapabilities) driver).getCapabilities();
            assertEquals("chrome", capabilities.getBrowserName());
            assertFalse(capabilities.getBrowserVersion().isBlank());

            driver.get("data:text/html,<title>pair-ok</title><p id='state'>ready</p>");
            assertEquals("pair-ok", driver.getTitle());
            assertEquals("ready", driver.findElement(By.id("state")).getText());
        } finally {
            driver.quit();
        }
    }
}

Publish the browser version with the immutable image and test revision. ChromeDriver version can be captured from provisioning output or driver logs. Capability shapes vary, so do not build critical logic around an undocumented nested Chrome-specific map.

Run the smoke test in the same user, container limits, network policy, and Grid path as the real suite. Then run a small critical scenario set and representative parallel load. Compatibility fixes session creation, but a new browser may expose product, rendering, or automation regressions that require separate analysis.

12. Selenium chromedriver version mismatch Release Checklist

Use this checklist for every browser pair update:

1. Select an official exact Chrome for Testing pair or resolve the installed supported Chrome through maintained Selenium Manager.
2. Record source metadata, version, platform, architecture, and artifact provenance.
3. Scan and publish artifacts through the approved supply chain.
4. Build an immutable worker or Grid node image.
5. Execute binary version checks and a local WebDriver smoke test.
6. Run critical flows and representative concurrency.
7. Confirm reports include browser, Selenium, image, and node details.
8. Promote intentionally and retain a rollback image.

For developer workstations, document the supported local path and a one-command health test. Remove legacy driver binaries and framework overrides after their owners migrate. For CI, alert when image manifests and runtime capabilities disagree.

Track session-not-created mismatches as environment provisioning failures, not product test failures. Do not reduce the suite's pass rate with hundreds of duplicate test failures when one image validation should have failed before fan-out. The Selenium CI pipeline guide can help place browser health checks before expensive shards.

A version policy is successful when updates are visible, reversible, and boring. The goal is not to freeze forever, but to make the browser pair an explicit tested dependency.

Interview Questions and Answers

Q: What causes a ChromeDriver version mismatch?

The ChromeDriver executable starting the session does not support the Chrome binary it launches. This often follows a browser auto-update, stale PATH entry, forced system property, old cache, or inconsistent Grid node image. I verify actual paths and versions before changing dependencies.

Q: How does Selenium Manager help?

Selenium Manager discovers local browsers and resolves drivers when a maintained Selenium binding creates a driver without a forced path. It can also manage browser versions such as Chrome for Testing in supported configurations. Network, proxy, cache, and security policy still matter.

Q: What is Chrome for Testing?

It is a versioned Chrome distribution intended for testing and automation, published with corresponding ChromeDriver assets. A team can install one exact browser and driver version together to avoid consumer Chrome's independent update behavior.

Q: Should Chrome and ChromeDriver have the same version?

For current Chrome for Testing releases, selecting the correspondingly versioned Chrome and ChromeDriver assets from the same published version is the clearest strategy. For an installed non-CfT browser, use official version-selection metadata or Selenium Manager rather than guessing from the major number alone.

Q: Why can mismatch persist after downloading a new driver?

Selenium may still select an older executable through PATH, a Java system property, environment variable, cache, wrapper, or Grid node. The ChromeDriver log and in-worker path diagnostics reveal the executable actually used. Fix the configuration source, not only the local file.

Q: Is disabling the ChromeDriver build check safe?

No. It removes an early compatibility guard without making the pair compatible. The result can be later protocol errors or unreliable behavior. I install or resolve a supported pair instead.

Q: How do you manage versions in Docker?

I resolve and install an exact approved pair during image build, record provenance, run a WebDriver health check, and publish an immutable image. Tests do not download a new latest browser at runtime. Updates go through validation and promotion.

Q: How do you diagnose mismatch on Selenium Grid?

I inspect the failed new-session response, requested capabilities, provider or Grid session data, and the actual node image. The client machine's driver is irrelevant to RemoteWebDriver. Inconsistent nodes are drained and rebuilt from one tested image.

Common Mistakes

• Downloading the latest ChromeDriver without checking the browser it will launch.
• Trusting filenames instead of executing both binaries with --version.
• Leaving a stale webdriver.chrome.driver system property in a base class.
• Running Selenium Manager and another auto-manager with unclear precedence.
• Deleting all shared caches before capturing which resolver selected the driver.
• Using webdriver.chrome.disableBuildCheck to suppress incompatibility.
• Adding browser startup flags to solve a clear version error.
• Letting a stable-channel URL resolve anew during every test run.
• Updating only Chrome or only ChromeDriver in a CI image.
• Using one cache key across operating systems and architectures.
• Checking versions on the RemoteWebDriver client instead of the Grid node.
• Retrying deterministic session creation failures across every test shard.
• Freezing browser versions indefinitely and missing supported security updates.
• Omitting browser and image versions from test reports.

Conclusion

A selenium chromedriver version mismatch is a dependency-resolution failure with a direct fix: identify the exact Chrome and ChromeDriver executables, remove stale selection overrides, and use a compatible pair managed by Selenium Manager or published together through Chrome for Testing. Keep the compatibility guard enabled and validate the result with a real WebDriver session.

Make the browser pair an explicit CI dependency. Resolve it in a controlled build, record its provenance and version, test it before suite fan-out, and promote an immutable worker or Grid image. That turns surprise session failures into a predictable browser update workflow.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Selenium chrome not reachable WebDriverException: Causes and Fixes
• Selenium ElementClickInterceptedException: Causes and Fixes
• Selenium ElementNotInteractableException: Causes and Fixes
• Selenium InvalidElementStateException: Causes and Fixes
• Selenium InvalidSelectorException: Causes and Fixes
• Selenium MoveTargetOutOfBoundsException: Causes and Fixes