The 'dial tcp: connect: host is unreachable' error occurs when a Docker container cannot establish a network connection to a target host. This is typically caused by network configuration issues, firewall rules, incorrect IP forwarding settings, or DNS resolution problems.
The "dial tcp: connect: host is unreachable" error indicates that Docker attempted to connect to a remote host but the network packets could not reach their destination. This is a low-level network error that occurs before any connection is even attempted—the network layer simply cannot find a route to the target IP address. This error can appear in several scenarios: - When pulling images from Docker Hub or other registries - When containers try to communicate with external services - During inter-container communication across different networks - When pushing images to a remote registry The "host is unreachable" message is distinct from "connection refused" (where the host is reachable but not accepting connections) or "connection timed out" (where packets are sent but no response is received). This error means the network stack on the Docker host or container determined there is no valid route to the destination.
IP forwarding must be enabled for Docker containers to communicate with external networks:
# Check current IP forwarding status
sysctl net.ipv4.ip_forward
# If it returns 0, enable it temporarily
sudo sysctl -w net.ipv4.ip_forward=1To make this permanent, add to /etc/sysctl.conf:
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -pAfter enabling, restart Docker:
sudo systemctl restart dockerFirewalls can block Docker's network traffic. Check and adjust your firewall settings:
For iptables:
# View current rules
sudo iptables -L -v -n
# Allow Docker bridge traffic
sudo iptables -A FORWARD -i docker0 -o eth0 -j ACCEPT
sudo iptables -A FORWARD -i eth0 -o docker0 -m state --state RELATED,ESTABLISHED -j ACCEPTFor firewalld (RHEL/CentOS/Fedora):
# Add docker0 to trusted zone
sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
sudo firewall-cmd --reloadFor ufw (Ubuntu):
# Allow Docker networks
sudo ufw allow from 172.16.0.0/12
sudo ufw allow from 10.0.0.0/8Note: On Fedora 32+, the default nftables backend can cause issues. You may need to configure Docker to use iptables.
Diagnose where the connectivity breaks:
# Run an alpine container with network tools
docker run --rm -it alpine sh
# Inside the container, test connectivity
ping -c 3 8.8.8.8 # Test raw IP connectivity
ping -c 3 google.com # Test DNS resolution
wget -O- http://example.com # Test HTTPIf ping to IP works but DNS fails, it's a DNS issue. If both fail, it's a network routing issue.
You can also test with explicit DNS:
docker run --rm --dns 8.8.8.8 alpine ping -c 3 google.comDNS issues are a common cause. Configure Docker to use reliable public DNS:
# Edit Docker daemon configuration
sudo nano /etc/docker/daemon.jsonAdd or update the DNS configuration:
{
"dns": ["8.8.8.8", "8.8.4.4", "1.1.1.1"]
}Restart Docker to apply:
sudo systemctl restart dockerFor Docker Desktop (Windows/Mac): Go to Settings > Docker Engine and add the DNS configuration to the JSON.
Docker's default bridge network uses 172.17.0.0/16, which can conflict with corporate or VPN networks:
# Check Docker's network configuration
docker network inspect bridge
# Check host routes
ip routeIf there's a conflict, configure a different subnet in /etc/docker/daemon.json:
{
"bip": "192.168.100.1/24",
"default-address-pools": [
{"base": "192.168.101.0/24", "size": 24}
]
}After making changes:
sudo systemctl restart dockerNetwork MTU (Maximum Transmission Unit) mismatches can cause unreachable hosts, especially with VPNs or cloud networks:
# Check host MTU
ip link show eth0
# Check Docker bridge MTU
ip link show docker0If the Docker MTU is higher than the host, set it in /etc/docker/daemon.json:
{
"mtu": 1400
}A safe value is usually 1400 or 1200. Then restart Docker:
sudo systemctl restart dockerFor docker-compose, you can also set MTU per network:
networks:
default:
driver: bridge
driver_opts:
com.docker.network.driver.mtu: 1400VPNs often interfere with Docker networking:
1. Test without VPN: Temporarily disconnect your VPN and try the Docker command again
2. If it works without VPN: Configure VPN split tunneling to exclude Docker traffic
For most VPNs, exclude these networks from the tunnel:
- 172.16.0.0/12 (Docker default range)
- registry-1.docker.io
- auth.docker.io
3. Alternative: Use host network mode temporarily:
docker run --network host your-imageNote: Host network mode is not recommended for production as it bypasses container network isolation.
If the network state is corrupted, reset Docker's network configuration:
# Stop all containers
docker stop $(docker ps -aq)
# Remove all containers
docker rm $(docker ps -aq)
# Prune networks
docker network prune -f
# Stop Docker
sudo systemctl stop docker
# Remove Docker network files (Docker will recreate them)
sudo rm -rf /var/lib/docker/network
# Start Docker
sudo systemctl start dockerThis will reset all Docker networks to their default state. Custom networks will need to be recreated.
If your server only has IPv6 or has misconfigured IPv6, connections to IPv4 hosts may fail:
# Check if you have IPv4 connectivity
ip -4 addr show
# If no IPv4 address, that's the issueIf you need to disable IPv6 for Docker:
# Edit /etc/sysctl.conf
sudo nano /etc/sysctl.confAdd:
net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1Apply and restart Docker:
sudo sysctl -p
sudo systemctl restart docker### Understanding the Error at the Network Level
The "host is unreachable" error corresponds to ICMP Destination Unreachable (Type 3, Code 1 - Host Unreachable) or an EHOSTUNREACH socket error. This means:
1. The routing table has no valid route to the destination
2. A router along the path sent back an unreachable message
3. ARP resolution failed for a local network destination
### Diagnosing with Network Tools
For advanced debugging, use these tools from the Docker host:
# Trace the route to see where it fails
traceroute registry-1.docker.io
# Check routing table
ip route show
# Monitor network traffic
sudo tcpdump -i docker0 -n
# Check iptables NAT rules (Docker uses these)
sudo iptables -t nat -L -v -n### Docker Desktop Considerations
Windows (WSL2): The WSL2 backend has its own network stack. Try:
- Restarting WSL: wsl --shutdown then restart Docker Desktop
- Check Windows firewall rules for "vpnkit" and "com.docker"
Windows (Hyper-V): The DockerNAT virtual switch may need reconfiguration:
1. Open Hyper-V Manager
2. Go to Virtual Switch Manager
3. Delete and recreate the DockerNAT switch
macOS: Docker Desktop uses a lightweight VM. Reset via:
Docker Desktop > Troubleshoot > Reset to factory defaults
### Container-to-Container Communication
If containers on different Docker networks can't reach each other:
# Connect container to multiple networks
docker network connect my-network container-name
# Or create an overlay network for multi-host
docker network create --driver overlay my-overlay### CI/CD Pipeline Issues
In CI/CD environments (GitHub Actions, GitLab CI, etc.), this error often indicates:
- The runner's network policy blocks outbound traffic
- Docker-in-Docker (dind) configuration issues
- Service containers not on the same network
Solutions:
1. Use --network host for build steps if allowed
2. Ensure services are on the same Docker network
3. Check CI platform documentation for network configuration
image 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