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

DockerINTERMEDIATEMEDIUMUpdated Feb 19, 2026· 1,369 views

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.

Quick fix

Fixes dial tcp: i/o timeout

# 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/
  1. Test basic network connectivity
  2. Configure DNS in Docker daemon
  3. Restart the Docker daemon
  4. Check and configure proxy settings
docker — error
# 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/
dial tcp: i/o timeout

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.

Typical symptoms

  • Docker pull commands hang for a long time before showing 'dial tcp: i/o timeout'
  • Error appears as 'net/http: TLS handshake timeout' or 'Client.Timeout exceeded while awaiting headers'
  • Docker push fails with timeout errors when trying to upload layers
  • Containers cannot reach external services or APIs
  • Docker login times out when authenticating with registries
  • Intermittent connectivity - commands work sometimes but fail other times
  • Error occurs more frequently when switching between networks (WiFi, VPN, LAN)

Common causes

  1. DNS resolution failures - Docker cannot resolve registry hostnames
  2. Firewall blocking outbound connections on port 443 (HTTPS) or port 53 (DNS)
  3. Corporate proxy not configured in Docker daemon settings
  4. Network MTU mismatch, especially when using VPNs
  5. Docker's internal DNS resolver (dnsmasq) configuration issues
  6. Slow or unstable network connection to Docker Hub or private registries
  7. WSL2 networking issues on Windows (DNS resolution degradation over time)
  8. Docker bridge network losing its IP configuration

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.

Advanced notes

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

powershell
# In PowerShell as Administrator
wsl --shutdown

Then restart Docker Desktop. For a more permanent fix, you can configure WSL2 to use a static DNS:

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

For 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:

bash
# Create a networkd override to ignore docker interfaces
sudo nano /etc/systemd/network/10-docker.network

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

[Link]
Unmanaged=yes

Then 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:

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

Frequently asked questions

What does "dial tcp: i/o timeout" mean?
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.
How do I fix "dial tcp: i/o timeout"?
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 causes "dial tcp: i/o timeout"?
DNS resolution failures - Docker cannot resolve registry hostnames Firewall blocking outbound connections on port 443 (HTTPS) or port 53 (DNS) Corporate proxy not configured in Docker daemon settings
Is the "dial tcp: i/o timeout" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading