How to fix net/http: timeout awaiting response headers in Docker

Often this error is temporary due to server load or transient network issues:

# Simply retry the command
docker pull your-image:tag

# For automated retries in scripts
for i in {1..5}; do
  docker pull your-image:tag && break
  echo "Attempt $i failed, retrying in 30 seconds..."
  sleep 30
done

If the error started suddenly and was working before, check the status of the registry:
- Docker Hub: https://status.docker.com/
- GitLab: https://status.gitlab.com/

Many users report that the issue resolves itself without any changes when the server load decreases.

Verify that your network can reach the registry server:

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

# Test connectivity to GitLab Container Registry
curl -v https://registry.gitlab.com/v2/

# Check DNS resolution
nslookup registry-1.docker.io
nslookup registry.gitlab.com

# Test with a simple HTTP request
wget --spider https://registry-1.docker.io/v2/

If curl/wget works but Docker doesn't, the issue is likely with Docker's network configuration or proxy settings.

DNS issues are a frequent cause of timeout errors. Configure Docker to use reliable public DNS servers:

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

Add the DNS configuration:

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

Apply the changes:

sudo systemctl daemon-reload
sudo systemctl restart docker

For Docker Desktop on Windows/Mac, go to Settings > Docker Engine and add the DNS configuration to the JSON settings.

If you're behind a corporate proxy, Docker needs explicit configuration:

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

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

Add your proxy settings:

[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,.internal.domain"

Reload and restart Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Verify the proxy is configured:

sudo systemctl show --property=Environment docker

Invalid or expired credentials in your Docker config can cause connection issues:

# Check your Docker config for auth issues
cat ~/.docker/config.json

# Log out and log back in to refresh credentials
docker logout
docker login

# For GitLab Container Registry
docker logout registry.gitlab.com
docker login registry.gitlab.com

If you see an invalid auth key or corrupted JSON, you can remove the credentials file and re-authenticate:

# Backup and remove the config
mv ~/.docker/config.json ~/.docker/config.json.backup
docker login

If public registries are consistently problematic, consider using alternative registries:

Use GitLab's built-in registry (if you have a GitLab instance):

# Log in to your GitLab registry
docker login registry.gitlab.com

# Pull from your own registry instead of Docker Hub
docker pull registry.gitlab.com/your-group/your-project/image:tag

Configure a registry mirror in /etc/docker/daemon.json:

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

Alternative public registries:
- GitHub Container Registry (ghcr.io)
- Amazon ECR Public (public.ecr.aws)
- Google Container Registry (gcr.io)
- Quay.io

VPN connections can interfere with Docker's network traffic:

1. Test without VPN: Temporarily disconnect your VPN and retry the Docker command

2. If it works without VPN, configure split tunneling to exclude Docker registries:
- Add registry-1.docker.io to your VPN's bypass list
- Add auth.docker.io and production.cloudflare.docker.com
- For GitLab: Add registry.gitlab.com

3. WSL users on Windows: After disconnecting VPN, you may need to restart WSL:

wsl --shutdown
wsl

Ensure your firewall allows Docker to communicate with registries:

# On Ubuntu, allow HTTPS traffic
sudo ufw allow out 443/tcp

# Check if specific ports are blocked (e.g., for GitLab registry)
sudo ufw allow 5050/tcp

# On RHEL/CentOS with firewalld
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

For corporate firewalls, ensure these domains are whitelisted:
- registry-1.docker.io
- auth.docker.io
- production.cloudflare.docker.com
- index.docker.io
- Your private registry domain

Sometimes a simple restart or network cleanup resolves the issue:

# Restart Docker daemon
sudo systemctl restart docker

# Clean up unused networks
docker network prune

# If the issue persists, try a more thorough cleanup
sudo systemctl stop docker
sudo rm -rf /var/lib/docker/network
sudo systemctl start docker

For Docker Desktop:
1. Right-click the Docker icon in the system tray
2. Select "Restart Docker"
3. If the issue persists, try "Troubleshoot" > "Reset to factory defaults" (backup images first)

Older Docker versions may have networking bugs. Update to the latest version:

On Linux:

# Update Docker using the official repository
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verify the version
docker --version

Docker Desktop:
1. Open Docker Desktop
2. Go to Settings > Software Updates
3. Click "Check for updates" and install the latest version

Users have reported that upgrading to Docker Desktop 4.35.1 or newer resolved this issue.