How to fix write: connection timed out in Docker

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.

Typical symptoms

• Docker push hangs then fails with 'write: connection timed out'
• Image pull operations stall and eventually timeout during layer downloads
• Containers cannot communicate with external APIs or databases
• Docker build fails when running apt-get, npm install, or pip install
• Intermittent failures - operations sometimes succeed, sometimes timeout
• Error appears more frequently on VPN connections or behind corporate proxies
• WSL2 environments experience increasing timeouts over multi-day uptime
• Operations work with '--network host' but fail with bridge networking

Common causes

1. MTU (Maximum Transmission Unit) mismatch between Docker bridge network and underlying network, especially common with VPNs
2. WSL2 networking stack degradation requiring periodic restarts on Windows
3. Firewall or security software interfering with Docker's network traffic
4. Network congestion or high latency causing write operations to exceed timeout thresholds
5. DNS resolution delays causing secondary timeout issues
6. Proxy misconfiguration or proxy server timeouts
7. Docker registry servers experiencing high load or rate limiting
8. Corporate network policies throttling or blocking Docker traffic

How to fix "write: connection timed out"

sudo systemctl restart docker

# Open PowerShell as Administrator
wsl --shutdown

# Wait a few seconds, then restart Docker Desktop

docker pull hello-world

# Check current MTU on docker0
ip link show docker0

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

sudo nano /etc/docker/daemon.json

{
  "mtu": 1400
}

sudo systemctl restart docker

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

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

sudo nano /etc/docker/daemon.json

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

sudo systemctl restart docker

docker run --rm alpine nslookup docker.com

# 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

# Ubuntu
sudo ufw disable

# CentOS/RHEL
sudo systemctl stop firewalld

# 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

[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"

sudo systemctl daemon-reload
sudo systemctl restart docker

ipconfig /flushdns

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

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

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

sudo nano /etc/docker/daemon.json

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

sudo systemctl restart docker

# 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

Advanced notes

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

# Add:
[network]
generateResolvConf = false

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

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

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

services:
  app:
    networks:
      - vpn-compatible

# 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/"

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

# Or manually check the bridge
ip addr show docker0

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

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

[Link]
Unmanaged=yes

Frequently asked questions

What does "write: connection timed out" mean?

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.

How do I fix "write: connection timed out"?

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 causes "write: connection timed out"?

MTU (Maximum Transmission Unit) mismatch between Docker bridge network and underlying network, especially common with VPNs WSL2 networking stack degradation requiring periodic restarts on Windows Firewall or security software interfering with Docker's network traffic

Is the "write: connection timed out" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• The WSL distribution "docker-desktop" does not exist

  How to fix 'The WSL distribution docker-desktop does not exist' in Docker

  HIGH

• WORKDIR: cannot change directory to /app: no such file or directory

  How to fix 'WORKDIR: cannot change directory: no such file or directory' in Docker

  LOW

• Docker Desktop - Unexpected WSL error

  How to fix 'Unexpected WSL error' in Docker Desktop

  MEDIUM

• WORKDIR: path must be absolute

  How to fix 'WORKDIR: path must be absolute' in Docker

  LOW

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 🐙
  Docker network connection time outs to host over time - GitHub Issue(GitHub)
• 🐙
  Connection timeout for some outside connections on all Docker containers - GitHub Issue(GitHub)
• 💬
  How to solve i/o timeout error in docker pull - Stack Overflow(Stack Overflow)
• 💬
  Docker run connection timeout - Stack Overflow(Stack Overflow)
• 💬
  Docker: Network timed out - Docker Forums(Stack Overflow)
• 📖
  Docker daemon configuration - Official Documentation(Official Docs)
• 📝
  100 Common Docker Errors & Solutions - Dev.to