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.
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.
A simple restart often resolves transient network state issues:
# Linux
sudo systemctl restart docker
# Verify Docker is running
sudo systemctl status docker
# Test with a simple pull
docker pull hello-worldOn 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:
# In PowerShell (as Administrator)
wsl --shutdownThen restart Docker Desktop and wait for it to initialize fully before retrying.
DNS issues are a frequent cause of read timeouts. Configure Docker to use public DNS:
# Edit Docker daemon configuration
sudo nano /etc/docker/daemon.jsonAdd or update with reliable DNS servers:
{
"dns": ["8.8.8.8", "8.8.4.4", "1.1.1.1"]
}Restart Docker to apply:
sudo systemctl restart dockerFor Docker Desktop: Go to Settings > Docker Engine and add the DNS configuration to the JSON editor.
Corrupted network state or resource exhaustion can cause timeout issues:
# 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 dfIf disk space is low, clean up more aggressively:
# WARNING: This removes volumes too (data loss possible)
docker system prune -af --volumesAfter cleanup, restart Docker and retry the operation.
VPN connections often use smaller MTU values. If Docker's default MTU is too high, packets get fragmented and may be dropped:
# Check current MTU on docker0 interface
ip link show docker0
# If MTU is 1500, try lowering it
sudo ip link set dev docker0 mtu 1400For a permanent fix, add MTU to daemon.json:
{
"mtu": 1400
}Then restart Docker:
sudo systemctl restart dockerCommon MTU values:
- Standard Ethernet: 1500
- With VPN overhead: 1400
- Some VPNs may need: 1350 or lower
Corporate proxies can timeout long-running connections. Ensure Docker is properly configured:
# 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.confAdd 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,.example.com"Apply the changes:
sudo systemctl daemon-reload
sudo systemctl restart docker
# Verify proxy is configured
sudo systemctl show --property=Environment dockerIf timeouts persist, ask your network team if the proxy has connection timeout limits that need adjusting.
If using Docker Compose, increase the HTTP timeout for slow connections:
# 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 --buildYou can also add this to your shell profile (~/.bashrc or ~/.zshrc):
export COMPOSE_HTTP_TIMEOUT=200Note: This doesn't help with the Docker CLI directly (docker pull/push), but is useful for compose-based workflows.
If the issue only occurs during builds, try using the host network:
# 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:
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.
If Docker Hub is consistently slow or timing out, configure a registry mirror:
# Edit daemon.json
sudo nano /etc/docker/daemon.jsonAdd a mirror configuration:
{
"registry-mirrors": ["https://mirror.gcr.io"]
}Restart Docker:
sudo systemctl restart dockerAlternative mirrors:
- https://mirror.gcr.io (Google's mirror)
- Your cloud provider may offer regional mirrors
- Large organizations often run internal registry proxies
For intermittent issues, implement retry logic:
#!/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 1Usage:
chmod +x retry-pull.sh
./retry-pull.sh ubuntu:latestTimeouts are often transient, so retrying during off-peak hours can also help.
### 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:
# In PowerShell as Administrator
wsl --shutdownThen restart Docker Desktop. For a more permanent fix, configure WSL2 to use static DNS:
# In WSL2, create/edit /etc/wsl.conf
sudo nano /etc/wsl.conf
# Add:
[network]
generateResolvConf = falseThen set DNS manually:
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:
# 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.pcapLook 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:
# 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
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub