How to fix net/http: TLS handshake timeout in Docker

First, determine if the issue is Docker-specific or a general network problem:

# Test TLS connection to Docker Hub
curl -v https://registry-1.docker.io/v2/

# Test DNS resolution
nslookup registry-1.docker.io

# Check if you can reach the auth server
curl -v https://auth.docker.io/

If curl succeeds but Docker fails, the issue is likely with Docker's network configuration. If both fail, you have a network-level problem.

If you're behind a corporate proxy, configure Docker with the correct proxy settings:

# Create the systemd drop-in directory
sudo mkdir -p /etc/systemd/system/docker.service.d

# Create the proxy configuration file
sudo nano /etc/systemd/system/docker.service.d/proxy.conf

Add your proxy settings. Important: Use http:// (not https://) for the HTTPS_PROXY value if your proxy doesn't support HTTPS connections:

[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,registry-1.docker.io"

Reload and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Verify the settings:

sudo systemctl show --property=Environment docker

MTU mismatches are a common cause of TLS handshake timeouts, especially on VPN or virtualized networks. Lower the MTU to prevent packet fragmentation:

# Edit Docker daemon configuration
sudo nano /etc/docker/daemon.json

Add or update the MTU setting:

{
  "mtu": 1400
}

If that doesn't work, try an even lower value like 1300:

{
  "mtu": 1300
}

Restart Docker to apply:

sudo systemctl restart docker

Note: The default MTU is 1500, but VPNs and some cloud networks use smaller values due to encapsulation overhead.

DNS issues can delay connection setup and contribute to timeouts. Configure Docker to use reliable public DNS servers:

# Edit Docker daemon configuration
sudo nano /etc/docker/daemon.json

Add DNS settings:

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

Restart Docker:

sudo systemctl restart docker

For Docker Desktop (Windows/Mac): Go to Settings > Docker Engine and add the DNS configuration to the JSON editor.

Docker allows you to increase the default TLS handshake timeout. Set the DOCKER_CLIENT_TIMEOUT environment variable:

# Set a longer timeout (in seconds)
export DOCKER_CLIENT_TIMEOUT=120

# Then run your Docker command
docker pull nginx:latest

To make this permanent, add it to your shell profile:

echo 'export DOCKER_CLIENT_TIMEOUT=120' >> ~/.bashrc
source ~/.bashrc

For Docker daemon-level timeout, you can adjust the daemon configuration with the --tls-handshake-timeout flag if available in your Docker version.

VPNs and firewalls with deep packet inspection can interfere with TLS handshakes:

1. Temporarily disconnect your VPN and try the Docker command again
2. Temporarily disable your firewall to test:

# On Ubuntu/Debian
sudo ufw disable
docker pull nginx:latest
sudo ufw enable

# On CentOS/RHEL
sudo systemctl stop firewalld
docker pull nginx:latest
sudo systemctl start firewalld

If Docker works without VPN/firewall, configure exceptions:
- Allow outbound connections on port 443 to registry-1.docker.io
- Add Docker Hub domains to your VPN's split tunnel configuration
- Disable TLS inspection for Docker registry traffic

IPv6 can sometimes cause connectivity issues with Docker registries:

# Add to /etc/sysctl.conf
sudo nano /etc/sysctl.conf

Add these lines:

net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1
net.ipv6.conf.lo.disable_ipv6=1

Apply the changes:

sudo sysctl --system

Restart Docker:

sudo systemctl restart docker

For macOS: Disable IPv6 in System Preferences > Network > Advanced > TCP/IP.

Docker versions 28.0.2 through 28.1.1 have been reported to cause TLS handshake timeout issues. Check your version:

docker version

If you're running an affected version, consider downgrading to 28.0.1:

# On Ubuntu/Debian - install specific version
sudo apt-get install docker-ce=5:28.0.1-1~ubuntu.22.04~jammy

# Or upgrade to the latest version if a fix has been released
sudo apt-get update && sudo apt-get upgrade docker-ce

Check the Docker release notes for fixes related to TLS handshake issues.

Sometimes Docker gets stuck in an inconsistent state. A simple restart can resolve transient issues:

# Restart Docker daemon
sudo systemctl restart docker

# Retry the pull command
docker pull nginx:latest

If the error is intermittent, use a retry loop:

for i in {1..5}; do
  docker pull nginx:latest && break
  echo "Attempt $i failed. Retrying in 10 seconds..."
  sleep 10
done

For CI/CD pipelines, add retry logic to handle transient failures.

If Docker Hub is consistently slow or unreliable from your location, configure a registry mirror:

# Edit daemon.json
sudo nano /etc/docker/daemon.json

Add a mirror:

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

Restart Docker:

sudo systemctl restart docker

Other mirror options:
- Your cloud provider may offer a regional mirror
- Corporate environments often have internal registry mirrors
- Consider using alternative registries like ghcr.io or quay.io for specific images