How to Fix Docker Pull Timeout or Connection Error

In this tutorial, you'll learn about How to Fix Docker Pull Timeout or Connection Error. We cover key concepts, practical examples, and best practices.

You run docker pull and get net/http: TLS handshake timeout or dial tcp: i/o timeout — Docker cannot reach the registry due to network issues, DNS problems, or proxy misconfiguration.

The Problem

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

Or:

Error response from daemon: Head "https://registry-1.docker.io/v2/":
dial tcp: lookup registry-1.docker.io: no such host

Step-by-Step Fix

Step 1: Check internet connectivity

ping -c 3 registry-1.docker.io

Or:

curl -I https://registry-1.docker.io/v2/

Step 2: Configure Docker DNS

Edit or create /etc/docker/daemon.json:

{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

Restart Docker:

sudo systemctl restart docker

Step 3: Configure HTTP proxy

If behind a corporate proxy, create /etc/systemd/system/docker.service.d/proxy.conf:

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"

Reload and restart:

sudo systemctl daemon-reload && sudo systemctl restart docker

Step 4: Use a registry mirror

Add to /etc/docker/daemon.json:

{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

Restart Docker:

sudo systemctl restart docker

Step 5: Increase pull timeout

For large images, increase the timeout:

{
  "max-concurrent-downloads": 3,
  "max-download-attempts": 5
}

Step 6: Verify /etc/hosts entries

If DNS resolution fails, check for incorrect host entries:

grep registry-1.docker.io /etc/hosts

If there is a wrong entry, remove it. Docker resolves registry hostnames via the system DNS or the DNS configured in daemon.json.

Step 7: Retry with explicit platform

docker pull --platform linux/amd64 nginx

This forces a specific architecture, useful when multi-arch manifests are not resolving correctly.

Step 8: Restart Docker and retry

sudo systemctl restart docker
docker pull nginx

A full restart clears stale network connections and DNS cache inside the Docker daemon.

Prevention Tips

• Use registry mirrors in regions with slow Docker Hub access
• Configure proxy settings before first use
• Use smaller base images like alpine to reduce download size
• Pre-pull images in CI pipelines
• Monitor Docker daemon logs with journalctl -u docker

Common Mistakes with pull timeout

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world DOCKER code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ