CI "read tcp ... connection reset by peer"

By Kaveh Alemi·Latchkey

A read on an open TCP socket failed because the peer sent a reset. In CI (often from Go tooling or the Docker client) this is a transient upstream/network blip during a transfer.

What this error means

A pull, push, or API call fails with read tcp <local>-><remote>: connection reset by peer. Re-running the unchanged job usually succeeds.

shell

Get "https://registry-1.docker.io/v2/": read tcp 10.0.0.5:51234->44.205.64.79:443: read: connection reset by peer

Common causes

The upstream reset the connection mid-read

A load balancer or server dropped the in-flight connection, often under load or during a restart.

Transient network instability

Brief packet loss or a path change surfaces as a TCP reset on the read side.

How to fix it

Retry the operation

Bounded retries absorb a single reset.

shell

for i in 1 2 3; do
  docker pull "$IMAGE" && break
  sleep $((i*10))
done

Reduce stress and shorten the path

Lower transfer concurrency.
Use a registry mirror/cache closer to the runner.
Authenticate to avoid throttle-driven resets.

How to prevent it

Retry network transfers in CI.
Use a caching mirror for images.
On managed runners, transient TCP resets are detected and the job is automatically retried, so a one-off reset does not fail the build.

Frequently asked questions

What causes "read tcp reset"?

A load balancer or server dropped the in-flight connection, often under load or during a restart.

How do I fix read tcp reset?