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.
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.
First, verify that your host machine can reach the internet and Docker Hub:
# 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.
Docker may be using an unreachable DNS server. Configure it to use public DNS servers:
# Create or edit the Docker daemon configuration
sudo nano /etc/docker/daemon.jsonAdd or update the DNS settings:
{
"dns": ["8.8.8.8", "8.8.4.4", "1.1.1.1"]
}Then restart Docker:
sudo systemctl restart dockerOn Docker Desktop (Windows/macOS):
Go to Settings > Docker Engine and add the DNS configuration there.
A simple restart often resolves transient network 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:
Right-click the Docker icon in the system tray and select "Restart".
On WSL2:
If issues persist, try restarting WSL:
# In PowerShell (as Administrator)
wsl --shutdownThen restart Docker Desktop.
If you're behind a corporate proxy, Docker needs to be configured to use it:
# 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 the proxy is configured
sudo systemctl show --property=Environment dockerEnsure your firewall allows Docker to make outbound connections:
# 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 firewalldIf Docker works with the firewall disabled, add rules to allow Docker traffic:
# Allow Docker to access DNS (port 53) and HTTPS (port 443)
sudo ufw allow out 53
sudo ufw allow out 443
sudo ufw enableVPNs often cause MTU (Maximum Transmission Unit) mismatches that lead to timeout errors:
# 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 1400For a permanent fix, add MTU to daemon.json:
{
"mtu": 1400
}Then restart Docker:
sudo systemctl restart dockerIf the issue only occurs during builds, try using the host network:
# Build with host networking
docker build --network host -t myimage .Or run containers with host networking to diagnose:
docker run --network host -it alpine ping google.comIf host networking works but bridge doesn't, the issue is with Docker's bridge network configuration.
For slow connections, you can increase Docker's timeout settings. For Docker Compose:
# Set a longer timeout (in seconds)
export COMPOSE_HTTP_TIMEOUT=200
# Then run your compose command
docker-compose upFor Docker CLI, timeouts are generally not configurable, but you can reduce load by pulling images individually rather than in parallel.
If Docker Hub is consistently slow or blocked, 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 dockerYou can also use other mirrors like Docker's own mirror or regional mirrors provided by cloud providers.
### WSL2-Specific Issues
Windows Subsystem for Linux 2 (WSL2) is known to have DNS resolution issues that worsen over time. The connection to the Windows host's DNS resolver can degrade, causing timeout errors. If you notice timeouts appearing after your system has been running for a while:
# In PowerShell as Administrator
wsl --shutdownThen restart Docker Desktop. For a more permanent fix, you can configure WSL2 to use a static DNS:
# In WSL2, edit /etc/wsl.conf
sudo nano /etc/wsl.conf
# Add:
[network]
generateResolvConf = false
# Then manually set DNS
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.confFor Rancher Desktop users, enable experimentalHostResolver in settings.json.
### Bridge Network IP Loss
On systems using systemd-networkd, the docker0 bridge interface can lose its IPv4 address after network changes. This causes all container networking to fail. To fix:
# Create a networkd override to ignore docker interfaces
sudo nano /etc/systemd/network/10-docker.network
# Add:
[Match]
Name=docker0 br-*
[Link]
Unmanaged=yesThen restart networkd and Docker.
### Rootless Docker Considerations
In rootless Docker mode, networking works differently. If you experience timeout issues:
1. Ensure slirp4netns or pasta is installed for networking
2. Check that your user's XDG_RUNTIME_DIR is set correctly
3. RootlessKit may need additional configuration for DNS
### Debugging Network Issues
To debug complex networking issues, you can inspect Docker's network configuration:
# List all Docker networks
docker network ls
# Inspect the bridge network
docker network inspect bridge
# Check iptables rules Docker created
sudo iptables -t nat -L -n -v
# Test DNS from inside a container
docker run --rm alpine nslookup google.comimage 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