Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker pull fails with net/http: TLS handshake timeout from the registry

Errornet/http: TLS handshake timeout

Short answer

The Docker daemon, not your shell, opens the connection to the registry, and its TLS handshake did not finish in time. The usual causes are a corporate proxy that only your shell knows about, or a slow direct route to Docker Hub. Give the daemon its proxy settings, or pull through a registry mirror.

  • Applies to Docker Engine 27, Docker Desktop 4.x, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which proxy settings the daemon itself has. The shell variables do not count.

    sudo systemctl show --property=Environment docker
    cat /etc/docker/daemon.json
  2. 2Match what you see, then jump to its fix

    1. 1curl works from the terminal, docker pull times out, and the daemon environment has no proxyThe daemon has no proxy configured, only your shell doesFix
    2. 2No proxy is needed on this network, but pulls from Docker Hub time out again and againThe direct route to Docker Hub is too slow or blockedFix

What does the error look like?

  • net/http: TLS handshake timeout

Cause 1 of 2

The daemon has no proxy configured, only your shell does

1Check

On a network that forces traffic through a proxy, the daemon needs the proxy in its own configuration. Exporting HTTP_PROXY in your terminal does not reach it. Docker Desktop ignores proxy settings in daemon.json.

sudo systemctl show --property=Environment docker

2Fix

Add a proxies block to daemon.json (hyphenated key names) and restart the daemon. On Docker Desktop set the proxy in Settings instead.

# /etc/docker/daemon.json
{
  "proxies": {
    "http-proxy": "http://proxy.example.com:3128",
    "https-proxy": "http://proxy.example.com:3128",
    "no-proxy": "*.test.example.com,.example.org,127.0.0.0/8"
  }
}

sudo systemctl restart docker

3Verify

The daemon reports the proxy and the pull completes.

sudo systemctl show --property=Environment docker
docker pull hello-world

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 2

The direct route to Docker Hub is too slow or blocked

1Check

A registry mirror caches Docker Hub images and serves later requests from the local copy, so the daemon makes fewer long trips to the public registry. Check whether one is set.

cat /etc/docker/daemon.json

2Fix

Point the daemon at a mirror you run or are given, then reload Docker.

# /etc/docker/daemon.json
{
  "registry-mirrors": ["https://<my-docker-mirror-host>"]
}

sudo systemctl restart docker

3Verify

The pull no longer times out.

docker pull hello-world

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Set the proxy in the daemon configuration when you set it for the shell, and keep both in one script.
  • Pull images in CI through a mirror or cache close to the runners.
  • Keep the no-proxy list correct for internal registries.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.