Docker "net/http: TLS handshake timeout" on pull in CI

By Daniel Zoghalchali·Latchkey

The Docker daemon connected to the registry but the TLS handshake did not finish in time. TCP succeeded, so this is not a firewall block; it is a slow, congested, or throttled path where the handshake packets are delayed.

What this error means

docker pull fails with "net/http: TLS handshake timeout", sometimes only for large layers or under registry rate limits.

Error response from daemon: Get "https://registry-1.docker.io/v2/":
net/http: TLS handshake timeout

Common causes

A congested or throttled path to the registry

A slow proxy, saturated egress, or registry rate limiting delays handshake packets past the timeout.

Too many concurrent pulls saturate the link

Parallel layer downloads can starve the handshake of bandwidth so it times out.

How to fix it

Retry and reduce concurrency

Retry the pull, and lower the daemon's concurrent download limit so handshakes get bandwidth.

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

Limit parallel layer downloads

Cap concurrent downloads in the daemon config so the TLS handshake is not starved.

{
  "max-concurrent-downloads": 3
}

How to prevent it

• Use a registry mirror or pull-through cache close to the runner.
• Cap concurrent downloads so handshakes are not starved on a slow link.
• Add retries around image pulls so a transient handshake timeout self-heals.

Frequently asked questions

Related guides

References

• GitHub Actions documentation