How to fix write: connection timed out in Docker

DockerINTERMEDIATEMEDIUM

The 'write: connection timed out' error occurs when Docker fails to complete a network write operation within the expected time. This typically happens during image push/pull operations, container-to-container communication, or when connecting to external services due to network congestion, firewall rules, or MTU mismatches.

What this error means

The "write: connection timed out" error in Docker indicates that a network operation failed because data could not be transmitted within the allowed timeout period. Unlike a "connection refused" error (which happens immediately), this timeout error means Docker successfully established a connection but then failed to send or receive data through it. This error commonly appears in several scenarios: - **During `docker push` or `docker pull`**: When uploading or downloading image layers, the connection may be established but data transfer stalls or fails. - **Container networking**: When containers try to communicate with each other or external services, write operations can time out due to network issues. - **Build operations**: When Dockerfiles fetch dependencies from the internet, network timeouts can interrupt the build process. The root cause is typically network-related: unstable connections, packet loss, MTU mismatches (especially with VPNs), DNS resolution delays, or firewall/proxy interference. On Windows with WSL2, this error can also occur when the WSL2 network integration degrades over time.

How to fix "write: connection timed out"

1Restart Docker and WSL (Windows)

The most common fix, especially on Windows with WSL2, is to restart the Docker daemon:

On Linux:

bash

sudo systemctl restart docker

On Windows (WSL2):

powershell

# Open PowerShell as Administrator
wsl --shutdown

# Wait a few seconds, then restart Docker Desktop

On macOS:
Click the Docker Desktop icon in the menu bar and select "Restart".

After restarting, test with a simple operation:

bash

docker pull hello-world

2Configure MTU settings for VPN compatibility

VPNs typically require a lower MTU (Maximum Transmission Unit) value. Docker defaults to 1500, but VPNs often need 1400 or lower:

bash

# Check current MTU on docker0
ip link show docker0

# Check your host network MTU
ip link show eth0  # or your primary interface

Create or edit the Docker daemon configuration:

bash

sudo nano /etc/docker/daemon.json

Add MTU configuration:

json

{
  "mtu": 1400
}

Restart Docker to apply:

bash

sudo systemctl restart docker

For Docker Compose, you may also need to set MTU in your compose file:

yaml

networks:
  default:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1400

3Test with host networking

Bypass Docker's bridge network to determine if the issue is network-layer specific:

bash

# Test connectivity with host network
docker run --rm --network host alpine wget -O /dev/null https://registry-1.docker.io/v2/

# Build using host network
docker build --network host -t myimage .

If host networking works but bridge doesn't, the problem is with Docker's virtual networking. Focus on MTU and firewall configuration.

4Configure DNS settings

DNS resolution issues can cause cascading timeout problems. Configure Docker to use reliable public DNS:

bash

sudo nano /etc/docker/daemon.json

Add DNS servers:

json

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

Restart Docker:

bash

sudo systemctl restart docker

On Docker Desktop (Windows/macOS):
Go to Settings > Docker Engine and add the DNS configuration there.

Verify DNS is working from inside a container:

bash

docker run --rm alpine nslookup docker.com

5Check and configure firewall rules

Firewalls may be silently dropping or delaying Docker's traffic:

bash

# Check for firewall issues (Linux)
sudo iptables -L -n -v | grep -E 'DROP|REJECT'

# Allow Docker interface through firewall
sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
sudo firewall-cmd --reload

# Or with ufw
sudo ufw allow in on docker0
sudo ufw allow out on docker0

Temporarily disable firewall to test (re-enable after!):

bash

# Ubuntu
sudo ufw disable

# CentOS/RHEL
sudo systemctl stop firewalld

If disabling the firewall fixes the issue, add specific rules to allow Docker traffic.

6Configure proxy settings

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

bash

# Create systemd override directory
sudo mkdir -p /etc/systemd/system/docker.service.d

# Create proxy configuration
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,docker-registry.local"

Apply changes:

bash

sudo systemctl daemon-reload
sudo systemctl restart docker

On Docker Desktop:
Go to Settings > Resources > Proxies and configure your proxy settings.

7Flush DNS cache

Stale DNS entries can cause connection issues. Clear the DNS cache:

On Windows:

powershell

ipconfig /flushdns

On macOS:

bash

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

On Linux:

bash

# systemd-resolved
sudo systemd-resolve --flush-caches

# Or restart the DNS service
sudo systemctl restart systemd-resolved

Then restart Docker and retry your operation.

8Use a registry mirror

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

bash

sudo nano /etc/docker/daemon.json

Add a mirror:

json

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

Restart Docker:

bash

sudo systemctl restart docker

Available mirrors include:
- Google: https://mirror.gcr.io
- Azure: https://dockerhub.azk8s.cn (China)
- Alibaba: https://registry.cn-hangzhou.aliyuncs.com (China)

9Check for rate limiting

Docker Hub rate limits unauthenticated pulls. If you're hitting limits, authenticate:

bash

# Log in to Docker Hub
docker login

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

Consider upgrading to Docker Pro or using a private registry for heavy usage.

Advanced notes

### WSL2-Specific Troubleshooting

Windows Subsystem for Linux 2 has known networking issues that cause timeouts to worsen over time. The virtual network adapter can lose its connection reliability after extended uptime.

Permanent fix for WSL2 DNS issues:

bash

# In WSL2, prevent auto-generation of resolv.conf
sudo nano /etc/wsl.conf

# Add:
[network]
generateResolvConf = false

Then set a static DNS:

bash

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

Restart WSL: wsl --shutdown in PowerShell.

### MTU Deep Dive

The Maximum Transmission Unit defines the largest packet size that can be sent without fragmentation. When VPNs or overlay networks are involved, MTU mismatches cause packets to be silently dropped.

Diagnosing MTU issues:

bash

# Find the optimal MTU by testing with ping
# Start at 1500 and decrease until packets get through
ping -c 3 -M do -s 1472 registry-1.docker.io

# 1472 = 1500 (MTU) - 28 (IP + ICMP headers)
# If this fails, try 1372 (for VPNs with overhead)

Per-network MTU in Docker Compose:

yaml

networks:
  vpn-compatible:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1300

services:
  app:
    networks:
      - vpn-compatible

### Debugging Write Timeouts

To capture more details about where the timeout occurs:

bash

# Enable Docker debug logging
sudo nano /etc/docker/daemon.json
# Add: "debug": true

# View detailed logs
sudo journalctl -u docker -f

# Test with verbose curl from inside container
docker run --rm alpine sh -c "apk add curl && curl -v --connect-timeout 10 --max-time 30 https://registry-1.docker.io/v2/"

### Network Bridge Issues

If the docker0 bridge loses its IP configuration (common with systemd-networkd):

bash

# Recreate the bridge network
docker network rm bridge
sudo systemctl restart docker

# Or manually check the bridge
ip addr show docker0

To prevent systemd-networkd from interfering:

bash

sudo nano /etc/systemd/network/10-docker.network

# Add:
[Match]
Name=docker0 br-* veth*

[Link]
Unmanaged=yes

How to fix write: connection timed out in Docker

What this error means

Typical symptoms

Common causes

How to fix "write: connection timed out"

Advanced notes

Related errors

Official resources & further reading