Self-Healing CI: Recovering a Failed Browser Binary Download (Playwright/Cypress)

A browser binary that fails to download is a network blip on a large fetch, not a broken test setup -- the same install usually completes on a retry.

The problem

A test setup step fails while downloading a browser binary -- Playwright’s install or Cypress’s binary fetch -- with a timeout, reset, or partial download. The versions are valid and the CDN is up; the large fetch hit a transient network problem. A human re-runs the job and the browser installs cleanly.

Typical symptom

Error: Failed to download Chromium ... Download failed: server returned code 503
# or
Cypress failed to download the binary: read ECONNRESET

Why it happens

Browser binaries are large downloads from a CDN, and a single big transfer is more exposed to a brief network blip, a momentary CDN 5xx, or a reset connection than a small request would be.

It is a transient fetch failure, not a setup problem: nothing about the test config changed, and the same download completes once the fetch is retried or pulled from a warmed cache.

The manual fix

Manual mitigations for browser binary downloads:

Re-run the job to retry the browser install.
Cache the browser binaries between runs so they are not re-downloaded each time.
Wrap the install in a bounded retry, or use the tool’s own download-retry setting.

Manual retry

npx playwright install --with-deps   || (sleep 5 && npx playwright install --with-deps)

How this gets automated

A failed browser download has a recognizable transient signature -- a timeout, reset, or 5xx on a large 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 binary is genuinely unavailable across retries, distinguishing a blip from a real version or availability problem.