docker pull fails with net/http: TLS handshake timeout from the registry
net/http: TLS handshake timeoutShort 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.
Fix it fast
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.json2Match what you see, then jump to its fix
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 docker2Fix
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 docker3Verify
The daemon reports the proxy and the pull completes.
sudo systemctl show --property=Environment docker
docker pull hello-worldConfirmed by docs.docker.com
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.json2Fix
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 docker3Verify
The pull no longer times out.
docker pull hello-worldConfirmed by docs.docker.com
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
Servers
docker pull or push fails against a private registry without valid HTTPS
Error response from daemon: v1 ping attempt failed with error
Docker treats every registry as secure except local ones.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix