Self-Healing CI: Recovering a Docker Layer Pull That Resets
A Docker pull that resets while downloading a layer hit a network blip on a large blob, not a corrupt image -- the same pull resumes and completes on a retry.
The problem
A docker pull fails because the connection reset while downloading an image layer. The image, tag, and digest are valid; a large layer blob transfer was interrupted by a transient network problem. A human re-runs the job and the pull completes, resuming or re-fetching the layer.
failed to register layer: error pulling image ... unexpected EOF
read tcp ... connection reset by peer (downloading layer sha256:...)Why it happens
Each image layer is a separate blob download, and large layers are more exposed to a brief network blip or a reset connection than small requests, so one interrupted layer can fail the whole pull even though the image is intact in the registry.
It is transport flakiness, not a bad image: the digest is valid and the same layer downloads cleanly once the transfer is retried.
The manual fix
Manual mitigations for a layer pull reset:
- Re-run the job to retry the pull -- already-pulled layers are reused.
- Use a registry pull-through cache or mirror closer to the runner.
- Wrap the pull in a bounded retry loop.
docker pull "${IMAGE}" || (sleep 5 && docker pull "${IMAGE}")How this gets automated
A reset layer pull has a recognizable transient signature -- a reset or EOF on a blob transfer, not an auth or manifest error -- and the safe response is to retry, resuming completed layers. A self-healing CI pipeline detects the pull failure, retries the layer download, and only escalates if the image is genuinely unreachable, distinguishing a blip from a real registry or image problem.