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

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 300 views

The 'net/http: timeout awaiting response headers' error occurs when Docker's HTTP client does not receive a timely response from a registry server. This is typically caused by network connectivity issues, DNS problems, proxy misconfigurations, or server overload.

Quick fix

Fixes net/http: timeout awaiting response headers

# 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
  1. Wait and retry the command
  2. Check network connectivity to the registry
  3. Configure Docker DNS settings
  4. Configure proxy settings for Docker
docker — error
# 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
net/http: timeout awaiting response headers

What this error means

The "net/http: timeout awaiting response headers" error indicates that Docker initiated an HTTP request to a registry server (like Docker Hub, GitLab Container Registry, or a private registry) but did not receive the HTTP response headers within the expected time frame. When Docker communicates with a registry, it sends an HTTP request and expects to receive response headers first (like status codes, content-type, etc.) before the actual response body. This error occurs when that initial handshake takes too long, causing Go's HTTP client to cancel the request. This is a slightly different error from "Client.Timeout exceeded while awaiting headers" - while related, "timeout awaiting response headers" specifically indicates the connection was established but the server didn't respond in time. Common scenarios include: 1. The registry server is overloaded or slow to respond 2. A proxy or firewall is interfering with the connection 3. Network latency or packet loss is causing delays 4. The server is down or experiencing issues This error is particularly common in CI/CD environments like GitLab CI where Docker-in-Docker (dind) is used, or when pulling from registries during high-traffic periods.

Typical symptoms

  • Docker commands hang for a while before failing with 'timeout awaiting response headers'
  • GitLab CI/CD jobs fail at the preparation stage with this error
  • docker pull or docker push commands time out unexpectedly
  • Artifact uploads in CI pipelines fail with timeout errors
  • Error occurs intermittently - sometimes commands succeed on retry
  • The error often includes a URL like 'https://registry-1.docker.io/v2/' or a GitLab registry URL
  • Docker build fails when pulling base images from remote registries
  • Commands work on local machines but fail in CI/CD environments

Common causes

  1. Registry server is temporarily overloaded or experiencing high latency
  2. Network connectivity issues between Docker client and registry
  3. Corporate proxy or firewall blocking or slowing connections
  4. DNS resolution problems causing delayed connections
  5. VPN connection interfering with Docker network traffic
  6. Docker Hub or private registry service outage
  7. GitLab server overload when using GitLab Container Registry
  8. Insufficient timeout configuration for slow networks
  9. Invalid or expired authentication credentials in ~/.docker/config.json

How to fix "net/http: timeout awaiting response headers"

1Wait and retry the command

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

bash
# 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.

2Check network connectivity to the registry

Verify that your network can reach the registry server:

bash
# 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.

3Configure Docker DNS settings

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

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

Add the DNS configuration:

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

Apply the changes:

bash
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.

4Configure proxy settings for Docker

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

bash
# 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:

ini
[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:

bash
sudo systemctl daemon-reload
sudo systemctl restart docker

Verify the proxy is configured:

bash
sudo systemctl show --property=Environment docker
5Check and fix authentication credentials

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

bash
# 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:

bash
# Backup and remove the config
mv ~/.docker/config.json ~/.docker/config.json.backup
docker login
6Use a private or alternative registry

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

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

bash
# 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:

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

7Disconnect VPN or configure split tunneling

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:

powershell
wsl --shutdown
wsl
8Check firewall and allow Docker traffic

Ensure your firewall allows Docker to communicate with registries:

bash
# 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

9Restart Docker and prune network resources

Sometimes a simple restart or network cleanup resolves the issue:

bash
# 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)

10Update Docker to the latest version

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

On Linux:

bash
# 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.

Advanced notes

### Understanding Go HTTP Timeouts

Docker is written in Go, and this error comes from Go's net/http package. The "timeout awaiting response headers" specifically refers to the ResponseHeaderTimeout setting in Go's HTTP Transport. This timeout starts after the request is fully written and ends when the response headers are received.

Key timeout settings in Go's HTTP client:
- net.Dialer.Timeout: Time to establish TCP connection
- TLSHandshakeTimeout: Time for TLS handshake
- ResponseHeaderTimeout: Time waiting for response headers (this error)
- ExpectContinueTimeout: Time waiting for "100 Continue" response

### GitLab CI/CD Specific Issues

The error frequently appears in GitLab CI with Docker-in-Docker (dind):

bash
ERROR: Preparation failed: Post https://docker:dind: net/http: timeout awaiting response headers

Solutions for GitLab CI:
1. Increase the job timeout in .gitlab-ci.yml
2. Use services: with explicit pull policy
3. Cache images in your own GitLab registry
4. Use retry: directive for transient failures

Example .gitlab-ci.yml configuration:

yaml
build:
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  retry:
    max: 2
    when: runner_system_failure

### Windows-Specific Considerations

On Windows with Docker Desktop:
1. Check the "vEthernet (DockerNAT)" or "vEthernet (WSL)" adapter DNS settings
2. Open Network Connections (ncpa.cpl)
3. Set DNS servers to 8.8.8.8 and 8.8.4.4 on the Docker adapter

For WSL2 users, the DNS in WSL is auto-generated. You can override it:

bash
# Edit WSL config
sudo nano /etc/wsl.conf

Add:

ini
[network]
generateResolvConf = false

Then manually set DNS in /etc/resolv.conf.

### Debugging Network Issues

Enable Docker daemon debug logging:

bash
sudo nano /etc/docker/daemon.json
json
{
  "debug": true,
  "log-level": "debug"
}

View debug logs:

bash
sudo journalctl -u docker -f

### Difference from Similar Errors

This error is related to but distinct from:
- "Client.Timeout exceeded while awaiting headers": The full client timeout was exceeded
- "request canceled while waiting for connection": Could not establish the initial connection
- "context deadline exceeded": A context-based timeout (often in orchestrators)

All these errors indicate network/timeout issues but at different stages of the HTTP request lifecycle.

Frequently asked questions

What does "net/http: timeout awaiting response headers" mean?
The "net/http: timeout awaiting response headers" error indicates that Docker initiated an HTTP request to a registry server (like Docker Hub, GitLab Container Registry, or a private registry) but did not receive the HTTP response headers within the expected time frame. ) before the actual response body. This error occurs when that initial handshake takes too long, causing Go's HTTP client to cancel the request.
How do I fix "net/http: timeout awaiting response headers"?
The 'net/http: timeout awaiting response headers' error occurs when Docker's HTTP client does not receive a timely response from a registry server. This is typically caused by network connectivity issues, DNS problems, proxy misconfigurations, or server overload.
What causes "net/http: timeout awaiting response headers"?
Registry server is temporarily overloaded or experiencing high latency Network connectivity issues between Docker client and registry Corporate proxy or firewall blocking or slowing connections
Is the "net/http: timeout awaiting response headers" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading