SessionNotCreatedException: Fix Driver Mismatch

No test runs at all. Every test fails in setup with SessionNotCreatedException, complaining the driver version only supports a Chrome version you no longer have. Yesterday everything was green. Nobody changed the suite. What changed was Chrome itself, silently auto-updating overnight past the chromedriver binary checked into your repo or cached on the runner.

This error is uniquely demoralizing because it strikes before any test logic executes — there is no flaky line to fix, no wait to tune. Beginners reinstall browsers and drivers at random, sometimes landing on a matching pair by luck, until the next auto-update breaks it again. The cycle repeats monthly because the root cause was never addressed: versions were paired by accident, not by management.

This guide makes driver management boring on purpose. You will learn to read the version mismatch message in seconds, let Selenium Manager resolve drivers automatically on modern Selenium, and pin browser-plus-driver pairs explicitly in CI images where determinism matters. By the end, Chrome updates become non-events instead of red mornings.

Reading the Mismatch Message in Ten Seconds

The exception message is unusually generous: it states the driver version, the browser version, and the supported range in plain text. A typical line says chromedriver 114 supports Chrome 114 while the session found Chrome 116 — diagnosis complete before you open a second tab. Yet teams routinely scroll past it hunting for suite bugs, because startup failures feel like infrastructure weather instead of readable errors.

Train the ten-second read: find the two version numbers, name which side moved, and update that side toward the other. Chrome moved via auto-update is the common case, so the driver follows the browser — upgrade bindings, clear vendored drivers, or bump the pinned driver. A moved driver after a careless image edit is rarer and fixed by re-pinning. Direction matters because downgrading browsers fights auto-update policies you will lose to eventually.

Log both versions in your session fixture so every CI log opens with the pairing evidence. One line printing selenium, browser, and driver versions turns the next red morning into a thirty-second comparison against yesterday's green log. Messages this clear deserve to be read — make them impossible to miss by echoing them into your own setup output.

Selenium Manager: Stop Hand-Managing Drivers

Selenium Manager ships inside modern Selenium bindings and ends the download-unzip-chmod ritual. On first driver use it detects the installed browser's version, fetches the matching driver from the official distribution, caches it per version, and hands back a working session. Chrome for Testing endpoints back the supply chain, so the resolved pairs are canonical rather than scraped. Most teams can delete their driver ClearlySetup code entirely.

Adoption is an upgrade plus a deletion. Bump the selenium package past 4.6 — current releases are well beyond it — then remove Service paths pointing at vendored binaries, webdriver-manager wiring kept only from habit, and README steps describing manual installs. The plain webdriver.Chrome() constructor with options is the whole integration now. Keep an allowlist for Manager's cache and download hosts if your network restricts egress, since first-run fetching needs to reach the distribution endpoints.

The snippet shows the minimal modern setup and the version-logging fixture worth adding. Notice what is missing: no paths, no zips, no version constants. That absence is the feature. Hand-management made sense when drivers were wild; today it is mostly a way to pin one half of a pair while the other half roams. Let the Manager own the pairing on developer machines and throwaway runners.

import selenium
from selenium import webdriver

def make_driver():
    options = webdriver.ChromeOptions()
    options.add_argument("--no-sandbox")
    options.add_argument("--disable-dev-shm-usage")
    # No Service path: Selenium Manager resolves the matching
    # chromedriver for the installed Chrome automatically.
    return webdriver.Chrome(options=options)

def log_versions(driver):
    print("selenium", selenium.__version__)
    print("browser", driver.capabilities["browserVersion"])
    print("chromedriver", driver.capabilities["chrome"]["chromedriverVersion"])

Pinning Browser and Driver Together in CI

Automatics suit laptops; CI demands determinism. A pipeline that resolves latest at runtime can go red between runs with no commit, which destroys bisectability — the ability to blame a specific change for a failure. Pinned images fix both halves of the pair in one Dockerfile layer: a versioned browser install plus either Manager resolution against that exact browser or an equally versioned driver. Rebuilds are deliberate, logged, and reversible.

The pinning pattern installs Chrome from a versioned deb or the Chrome for Testing API at an explicit milestone, then smoke-tests session creation during the image build so a bad pair fails the build, not the test run. Dependabot or Renovate bumps the pins on schedule, and each bump runs the suite before merging — browser upgrades become ordinary tested changes. Keep the two versions adjacent in the Dockerfile with a comment naming the pairing, so no edit moves one without the other.

The snippet shows the shape: versioned install, build-time smoke test, runtime flags for containers. Note --no-sandbox and --disable-dev-shm-usage, without which Chrome crashes in unprivileged containers regardless of versions. Deterministic images plus Manager resolution inside them is belt and suspenders: the image fixes the browser, and resolution confirms the driver at runtime. Green builds stay green until you choose otherwise.

from selenium import webdriver

CHROME_VERSION = "126.0.6478.126"  # paired with driver via Manager

def make_ci_driver():
    options = webdriver.ChromeOptions()
    options.add_argument("--headless=new")
    options.add_argument("--no-sandbox")
    options.add_argument("--disable-dev-shm-usage")
    options.add_argument("--window-size=1920,1080")
    driver = webdriver.Chrome(options=options)
    return driver

def smoke_test():
    driver = make_ci_driver()
    try:
        driver.get("about:blank")  # build fails here on bad pairs
        assert driver.session_id, "no session established"
        print("pair OK:", driver.capabilities["browserVersion"])
    finally:
        driver.quit()

Clearing Stale Drivers That Shadow the Fix

Upgrading bindings or pins sometimes changes nothing, and the culprit is a stale driver earlier on the resolution path. Vendored binaries committed to the repo, explicit Service paths in conftest, webdriver-manager caches from older setups, and Manager caches holding a corrupt download all shadow fresh resolution. Each one silently wins over the correct driver, so the mismatch persists through upgrades that should have fixed it.

Hunt methodically: list every chromedriver on PATH, print any Service executable_path in your fixtures, and inspect the Manager cache directory for stale entries. Remove committed binaries from the repo — drivers are resolved artifacts, not source code — and delete explicit paths so Manager decides. Where webdriver-manager remains in use, pin its driver version call explicitly rather than letting it float, or migrate that project to Manager and drop the dependency.

The snippet shows the audit commands plus the fixture shape that avoids shadowing. Run the audit once per project and once per runner image; stale drivers hide in both. After clearing, the version log from your fixture should show the expected pair on the next run. Resolution can only pick the right driver when no stale copy outranks it.

from selenium import webdriver
from selenium.webdriver.chrome.service import Service

def make_driver_no_shadow():
    options = webdriver.ChromeOptions()
    options.add_argument("--headless=new")
    # No executable_path: any hardcoded path here would shadow
    # Selenium Manager and reintroduce the mismatch by hand.
    return webdriver.Chrome(options=options)

# Shell audit for stale drivers (run on the runner):
#   which -a chromedriver
#   ls ~/.cache/selenium
#   grep -rn "executable_path" tests/ conftest.py

Grid Nodes and Remote Sessions Drift Too

Remote WebDriver moves the handshake to the node, and nodes drift independently. Your laptop's perfect pairing means nothing when the Grid node runs last quarter's Chrome against this quarter's driver — the session fails with the same mismatch wearing a remote traceback. Node images updated on different schedules are the usual cause: infrastructure patches browsers while the test image pins drivers, or vice versa.

Debug at the node, not the client. The Grid console exposes node versions, and a direct version check over SSH settles it in seconds. Pair node browser and driver in a single image build with the same pinning discipline as CI runners, and roll nodes and hubs together so no node serves sessions its pair cannot honor. Log the node's reported versions in your remote fixture to keep the evidence client-side.

The snippet shows a remote fixture with node version logging. When mismatches appear, compare the logged node pair against the known-good pins instead of debugging test code. Grid multiplies capacity and multiplies version surfaces — each node is a pairing you own. Treat node images as release artifacts with versions, changelogs, and rollback, and remote mismatches become as rare as local ones.

from selenium import webdriver

GRID_URL = "http://grid-hub:4444/wd/hub"

def make_remote_driver():
    options = webdriver.ChromeOptions()
    options.add_argument("--headless=new")
    options.add_argument("--no-sandbox")
    options.add_argument("--disable-dev-shm-usage")
    driver = webdriver.Remote(command_executor=GRID_URL, options=options)
    caps = driver.capabilities
    print("node browser", caps.get("browserVersion"))
    print("node driver", caps.get("chrome", {}).get("chromedriverVersion"))
    return driver

Making the Next Mismatch a One-Minute Fix

Prevention is instrumentation plus policy. Instrumentation means the version log in every fixture, the build-time smoke test in every image, and a dashboard alert when runner browser versions change without a matching suite run. Policy means pinned CI pairs, Manager resolution elsewhere, no committed drivers, and browser upgrades as scheduled tested changes. Together they compress each future incident to version comparison plus a pin bump.

Write the runbook entry while this incident is fresh: symptom signature, the two version commands, the upgrade-or-pin decision tree, and the rollback step. Link it from the fixture's error message if your framework allows custom setup messages — the engineer who meets this at 8 AM should land on instructions, not a blank search box. Review the pins quarterly even when green, because silent drift is only silent until morning.

The deeper lesson is that startup dependencies deserve the same rigor as application dependencies. Lockfiles pin libraries; images must pin browsers with equal seriousness. A suite that manages its runtime this way treats Chrome releases as calendar events with owners and dates. The next mismatch still arrives eventually — but it arrives as a ticket with versions attached, fixed in minutes by whoever is on call.