Self-Healing CI: Auto-Retrying a Yarn Network Timeout
A Yarn install that times out fetching a tarball hit a congested registry moment, not a broken dependency -- the same install completes on a retry.
The problem
A yarn install fails with a network timeout while fetching a package tarball or metadata. The package and version exist and the lockfile is valid; one of many fetches hit a transient network problem. A human re-runs the job and the install completes cleanly.
error An unexpected error occurred: "https://registry.yarnpkg.com/... ESOCKETTIMEDOUT".
info Visit https://yarnpkg.com/en/docs/cli/install for documentation.Why it happens
Yarn fetches each package over its own request, so the more dependencies a project has, the more transfers can hit a brief network blip and time out even though every package is present and intact at the source.
It is transport flakiness, not a dependency error: the lockfile is correct and the same install completes once the failed fetches are retried.
The manual fix
Manual mitigations for a Yarn network timeout:
- Re-run the job to retry the install.
- Raise Yarn’s network timeout (
--network-timeout) and rely on its retry behavior. - Cache Yarn’s cache folder between runs and consider a registry mirror.
yarn install --frozen-lockfile --network-timeout 120000 || (sleep 5 && yarn install --frozen-lockfile)How this gets automated
A Yarn network timeout carries a recognizable transient signature -- a timeout on a fetch, not a missing-package error -- and the safe response is to retry the install. A self-healing CI pipeline detects the failure, retries package resolution, and only escalates if a package is genuinely unavailable, distinguishing a slow registry moment from a real dependency problem.