How to fix read: connection timed out in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 178 views

The 'read: connection timed out' error occurs when Docker cannot complete reading data from a network connection within the expected time. This typically indicates network instability, DNS resolution problems, proxy misconfiguration, firewall restrictions, or registry server issues.

Quick fix

Fixes read: connection timed out

# Linux
sudo systemctl restart docker

# Verify Docker is running
sudo systemctl status docker

# Test with a simple pull
docker pull hello-world
  1. Restart the Docker daemon
  2. Configure reliable DNS servers
  3. Clean up Docker resources and networks
  4. Check and adjust MTU settings (especially for VPN users)
docker — error
# Linux
sudo systemctl restart docker
# Verify Docker is running
sudo systemctl status docker
# Test with a simple pull
docker pull hello-world
read: connection timed out

What this error means

The "read: connection timed out" error in Docker indicates that while a TCP connection was successfully established, the subsequent read operation (receiving data) failed because no data arrived within the timeout period. This is different from a connection timeout, where the initial connection cannot be made at all. When Docker interacts with registries during `docker pull`, `docker push`, or other network operations, it establishes a connection and then waits to receive data. If the remote server stops responding mid-transfer, or if network conditions cause packet loss, Docker will eventually give up and report this timeout error. This error is particularly frustrating because it often occurs intermittently - the initial connection works, but data transfer stalls partway through. Common scenarios include slow or unstable internet connections, overloaded registry servers, packet loss on VPN connections, or network equipment dropping idle connections.

Typical symptoms

  • Docker pull commands hang for a long time before failing with 'read: connection timed out'
  • Image layers start downloading but stall partway through
  • Docker push fails after uploading some layers successfully
  • Error occurs more frequently with large images
  • Commands succeed sometimes but fail other times (intermittent)
  • Error appears after Docker was working fine (often during peak hours)
  • WSL2 users experience this error after extended system uptime
  • The error occurs more often when connected via VPN or corporate network

Common causes

  1. Unstable or slow internet connection causing packet loss during data transfer
  2. DNS resolution degradation over time (especially in WSL2 environments)
  3. Network equipment or ISP dropping idle or slow connections
  4. VPN MTU mismatch causing fragmented packets to be dropped
  5. Docker Hub or registry server experiencing high load or rate limiting
  6. Proxy server timing out long-running connections
  7. Firewall or IDS systems interrupting connections that appear stalled
  8. Docker's internal DNS resolver (dnsmasq) configuration issues

How to fix "read: connection timed out"

1Restart the Docker daemon

A simple restart often resolves transient network state issues:

bash
# Linux
sudo systemctl restart docker

# Verify Docker is running
sudo systemctl status docker

# Test with a simple pull
docker pull hello-world

On Docker Desktop (Windows/macOS):
Right-click the Docker icon in the system tray and select "Restart".

On WSL2:
If using WSL2 backend, also restart WSL:

powershell
# In PowerShell (as Administrator)
wsl --shutdown

Then restart Docker Desktop and wait for it to initialize fully before retrying.

2Configure reliable DNS servers

DNS issues are a frequent cause of read timeouts. Configure Docker to use public DNS:

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

Add or update with reliable DNS servers:

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

Restart Docker to apply:

bash
sudo systemctl restart docker

For Docker Desktop: Go to Settings > Docker Engine and add the DNS configuration to the JSON editor.

3Clean up Docker resources and networks

Corrupted network state or resource exhaustion can cause timeout issues:

bash
# Remove unused containers, networks, images, and build cache
docker system prune -af

# List all networks and remove orphaned ones
docker network ls
docker network prune

# Check Docker's disk usage
docker system df

If disk space is low, clean up more aggressively:

bash
# WARNING: This removes volumes too (data loss possible)
docker system prune -af --volumes

After cleanup, restart Docker and retry the operation.

4Check and adjust MTU settings (especially for VPN users)

VPN connections often use smaller MTU values. If Docker's default MTU is too high, packets get fragmented and may be dropped:

bash
# Check current MTU on docker0 interface
ip link show docker0

# If MTU is 1500, try lowering it
sudo ip link set dev docker0 mtu 1400

For a permanent fix, add MTU to daemon.json:

json
{
  "mtu": 1400
}

Then restart Docker:

bash
sudo systemctl restart docker

Common MTU values:
- Standard Ethernet: 1500
- With VPN overhead: 1400
- Some VPNs may need: 1350 or lower

5Configure proxy settings if behind corporate proxy

Corporate proxies can timeout long-running connections. Ensure Docker is properly configured:

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,.example.com"

Apply the changes:

bash
sudo systemctl daemon-reload
sudo systemctl restart docker

# Verify proxy is configured
sudo systemctl show --property=Environment docker

If timeouts persist, ask your network team if the proxy has connection timeout limits that need adjusting.

6Increase Docker Compose timeout

If using Docker Compose, increase the HTTP timeout for slow connections:

bash
# Set environment variable before running compose commands
export COMPOSE_HTTP_TIMEOUT=200

# Or set it inline
COMPOSE_HTTP_TIMEOUT=200 docker-compose pull
COMPOSE_HTTP_TIMEOUT=200 docker-compose up --build

You can also add this to your shell profile (~/.bashrc or ~/.zshrc):

bash
export COMPOSE_HTTP_TIMEOUT=200

Note: This doesn't help with the Docker CLI directly (docker pull/push), but is useful for compose-based workflows.

7Try using host network mode for builds

If the issue only occurs during builds, try using the host network:

bash
# Build with host networking (bypasses Docker's bridge network)
docker build --network host -t myimage .

For debugging, run a container with host networking to test connectivity:

bash
docker run --network host -it alpine sh
# Inside container:
wget -O /dev/null https://registry-1.docker.io/v2/

If host networking works but bridge doesn't, the issue is with Docker's network configuration, not your host's network.

8Configure a registry mirror

If Docker Hub is consistently slow or timing out, configure a registry mirror:

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

Add a mirror configuration:

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

Restart Docker:

bash
sudo systemctl restart docker

Alternative mirrors:
- https://mirror.gcr.io (Google's mirror)
- Your cloud provider may offer regional mirrors
- Large organizations often run internal registry proxies

9Retry with exponential backoff

For intermittent issues, implement retry logic:

bash
#!/bin/bash
# retry-pull.sh - Retry docker pull with exponential backoff
IMAGE="$1"
MAX_ATTEMPTS=5
DELAY=10

for i in $(seq 1 $MAX_ATTEMPTS); do
  echo "Attempt $i of $MAX_ATTEMPTS..."
  if docker pull "$IMAGE"; then
    echo "Success!"
    exit 0
  fi
  if [ $i -lt $MAX_ATTEMPTS ]; then
    echo "Failed, waiting ${DELAY}s before retry..."
    sleep $DELAY
    DELAY=$((DELAY * 2))
  fi
done

echo "All attempts failed"
exit 1

Usage:

bash
chmod +x retry-pull.sh
./retry-pull.sh ubuntu:latest

Timeouts are often transient, so retrying during off-peak hours can also help.

Advanced notes

### WSL2-Specific DNS Issues

Windows Subsystem for Linux 2 (WSL2) is known to have DNS resolution issues that worsen over time. The virtual network connection to the Windows host can degrade, causing increasing read timeouts:

powershell
# In PowerShell as Administrator
wsl --shutdown

Then restart Docker Desktop. For a more permanent fix, configure WSL2 to use static DNS:

bash
# In WSL2, create/edit /etc/wsl.conf
sudo nano /etc/wsl.conf

# Add:
[network]
generateResolvConf = false

Then set DNS manually:

bash
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
sudo chattr +i /etc/resolv.conf  # Prevent overwriting

### Understanding Read Timeouts vs Connection Timeouts

- Connection timeout: The initial TCP handshake fails - "dial tcp: i/o timeout"
- Read timeout: Connection established but data transfer fails - "read: connection timed out"

Read timeouts usually indicate:
1. The server is responding but slowly
2. Network congestion is causing packet loss
3. An intermediary (proxy, firewall) is closing idle connections

### Debugging with Packet Capture

For persistent issues, capture network traffic to identify where the timeout occurs:

bash
# Capture Docker network traffic
sudo tcpdump -i docker0 -w docker-traffic.pcap

# In another terminal, trigger the failing operation
docker pull ubuntu:latest

# Stop capture with Ctrl+C, then analyze
wireshark docker-traffic.pcap

Look for TCP retransmissions, which indicate packet loss in the network path.

### Rate Limiting Considerations

Docker Hub implements rate limiting:
- Anonymous pulls: 100 pulls per 6 hours
- Free account: 200 pulls per 6 hours
- Pro/Team: Unlimited

Rate limiting can manifest as slow connections that eventually timeout. Authenticate to check your status:

bash
# Login to Docker Hub
docker login

# Check your rate limit status
TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r '.token')
curl -s -H "Authorization: Bearer $TOKEN" "https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest" -D - 2>&1 | grep -i rate

### Firewall and IDS Interference

Some enterprise firewalls or Intrusion Detection Systems (IDS) terminate connections that appear "stalled" during large file transfers. Work with your network team to:

1. Whitelist Docker registry IPs
2. Increase connection idle timeout for Docker traffic
3. Disable deep packet inspection for registry traffic

Frequently asked questions

What does "read: connection timed out" mean?
The "read: connection timed out" error in Docker indicates that while a TCP connection was successfully established, the subsequent read operation (receiving data) failed because no data arrived within the timeout period. This is different from a connection timeout, where the initial connection cannot be made at all. When Docker interacts with registries during docker pull, docker push, or other network operations, it establishes a connection and then waits to receive data.
How do I fix "read: connection timed out"?
The 'read: connection timed out' error occurs when Docker cannot complete reading data from a network connection within the expected time. This typically indicates network instability, DNS resolution problems, proxy misconfiguration, firewall restrictions, or registry server issues.
What causes "read: connection timed out"?
Unstable or slow internet connection causing packet loss during data transfer DNS resolution degradation over time (especially in WSL2 environments) Network equipment or ISP dropping idle or slow connections
Is the "read: connection timed out" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading