Self-Healing CI: Recovering a ChromeDriver Download Version Mismatch
A ChromeDriver setup that fails to fetch a matching version usually hit a transient download or resolution blip, not a permanently incompatible driver -- re-resolving and retrying clears it.
The problem
A browser-test setup step fails because ChromeDriver could not download a build matching the installed Chrome, or the download itself failed. Compatible versions exist; the resolution/download hit a transient blip. A human re-runs the setup -- re-resolving the matching driver -- and it installs cleanly.
Error: Could not download ChromeDriver for Chrome version 126.0...
This version of ChromeDriver only supports Chrome version XXX (download failed)Why it happens
ChromeDriver setup resolves the matching driver build for the installed Chrome and downloads it over the network, so a momentary resolution blip or a failed download can surface as a mismatch even though a compatible driver is available.
It is a setup-time download/resolution race, not a permanent incompatibility: re-resolving and re-downloading the matching driver makes the same setup succeed.
The manual fix
Manual mitigations for a ChromeDriver mismatch:
- Re-run the setup so it re-resolves and re-downloads the matching driver.
- Use an auto-matching driver manager and cache the resolved driver between runs.
- Pin Chrome and ChromeDriver to known-compatible versions to remove resolution variance.
npx @puppeteer/browsers install chromedriver@stable || (sleep 5 && npx @puppeteer/browsers install chromedriver@stable)How this gets automated
A failed driver resolution/download has a recognizable transient signature when a compatible driver does exist, and the safe response is to re-resolve and retry. A self-healing CI pipeline detects the setup failure, retries driver resolution and download, and only escalates if no compatible driver is genuinely available, distinguishing a download blip from a real version incompatibility.