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

DockerINTERMEDIATEMEDIUM

The 'dial tcp: i/o timeout' error occurs when Docker cannot establish a network connection within the expected time. This typically indicates DNS resolution problems, network connectivity issues, firewall restrictions, or proxy misconfiguration.

What this error means

The "dial tcp: i/o timeout" error in Docker indicates that a TCP connection attempt failed because it took too long to establish. When Docker tries to connect to a registry (like Docker Hub), an external service, or even another container, it uses TCP/IP networking. If the connection cannot be established within the timeout period, you see this error. This error commonly appears during `docker pull`, `docker push`, or when containers try to reach external services. The underlying cause is usually related to network configuration rather than Docker itself - DNS servers may be unreachable, firewalls may be blocking outbound connections, or there may be issues with your network's routing. The error message often includes the target IP address and port, which can help identify whether it's a registry connection issue (typically port 443) or a DNS resolution problem (port 53). Understanding the exact network path helps narrow down the troubleshooting steps.

How to fix "dial tcp: i/o timeout"

1Test basic network connectivity

First, verify that your host machine can reach the internet and Docker Hub:

bash

# Test basic internet connectivity
ping -c 3 google.com

# Test connectivity to Docker Hub
ping -c 3 registry-1.docker.io

# Test HTTPS connectivity to Docker Hub
curl -v https://registry-1.docker.io/v2/

If these commands fail, the issue is with your host's network configuration, not Docker specifically.

2Configure DNS in Docker daemon

Docker may be using an unreachable DNS server. Configure it to use public DNS servers:

bash

# Create or edit the Docker daemon configuration
sudo nano /etc/docker/daemon.json

Add or update the DNS settings:

json

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

Then restart Docker:

bash

sudo systemctl restart docker

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

3Restart the Docker daemon

A simple restart often resolves transient network 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:
Right-click the Docker icon in the system tray and select "Restart".

On WSL2:
If issues persist, try restarting WSL:

powershell

# In PowerShell (as Administrator)
wsl --shutdown

Then restart Docker Desktop.

4Check and configure proxy settings

If you're behind a corporate proxy, Docker needs to be configured to use it:

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 the proxy is configured
sudo systemctl show --property=Environment docker

5Check firewall rules

Ensure your firewall allows Docker to make outbound connections:

bash

# Check if firewall is blocking connections (Linux)
sudo iptables -L -n | grep -i drop
sudo iptables -L -n | grep -i reject

# Temporarily disable firewall to test (revert after testing!)
# Ubuntu/Debian
sudo ufw disable

# CentOS/RHEL
sudo systemctl stop firewalld

If Docker works with the firewall disabled, add rules to allow Docker traffic:

bash

# Allow Docker to access DNS (port 53) and HTTPS (port 443)
sudo ufw allow out 53
sudo ufw allow out 443
sudo ufw enable

6Fix MTU issues (especially with VPNs)

VPNs often cause MTU (Maximum Transmission Unit) mismatches that lead to timeout errors:

bash

# Check current MTU on docker0 interface
ip link show docker0

# Lower the MTU to work with VPN (1400 is usually safe)
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

7Try using the host network for builds

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

bash

# Build with host networking
docker build --network host -t myimage .

Or run containers with host networking to diagnose:

bash

docker run --network host -it alpine ping google.com

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

8Increase timeout values

For slow connections, you can increase Docker's timeout settings. For Docker Compose:

bash

# Set a longer timeout (in seconds)
export COMPOSE_HTTP_TIMEOUT=200

# Then run your compose command
docker-compose up

For Docker CLI, timeouts are generally not configurable, but you can reduce load by pulling images individually rather than in parallel.

9Use a registry mirror

If Docker Hub is consistently slow or blocked, 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

You can also use other mirrors like Docker's own mirror or regional mirrors provided by cloud providers.

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

What this error means

Typical symptoms

Common causes

How to fix "dial tcp: i/o timeout"

Advanced notes

Related errors

Official resources & further reading