Self-Healing CI: Recovering a Failed geckodriver Download
A geckodriver download that fails hit a network blip on a release asset fetch, not a broken Firefox test setup -- the same download completes on a retry.
The problem
A Firefox-test setup step fails while downloading geckodriver -- a timeout, reset, or 5xx fetching the release asset. The version is valid and the asset exists; the download hit a transient network problem. A human re-runs the setup and geckodriver installs cleanly.
Error: failed to download geckodriver: server returned 503
read ECONNRESET (downloading geckodriver release asset)Why it happens
geckodriver is downloaded as a release asset over HTTP, and a single binary transfer is exposed to a brief network blip or a momentary 5xx more than a small request would be.
It is a transient fetch failure, not a setup problem: the version is valid and the same asset downloads once the fetch is retried or pulled from a cache.
The manual fix
Manual mitigations for a geckodriver download:
- Re-run the job to retry the download.
- Cache the resolved geckodriver between runs so it is not re-fetched each time.
- Use a driver manager that retries downloads, or mirror the asset internally.
npx @puppeteer/browsers install geckodriver || (sleep 5 && npx @puppeteer/browsers install geckodriver)How this gets automated
A failed geckodriver download has a recognizable transient signature -- a timeout, reset, or 5xx on an asset fetch -- and the safe response is to retry, ideally from a cache. A self-healing CI pipeline detects the download failure, retries the install, and only escalates if the asset is genuinely unavailable, distinguishing a blip from a real version or availability problem.