The 'dial tcp: connect: network is unreachable' error occurs when Docker cannot establish a TCP connection to an external host or registry. This typically indicates DNS configuration issues, missing network routes, IPv6-only environments, or problems with Docker's network bridge.
When you encounter "dial tcp: connect: network is unreachable" in Docker, it means the Docker daemon or container cannot establish a network connection to the specified IP address and port. The TCP handshake fails before it even begins because the operating system's network stack has no route to reach the destination. This error commonly appears when: - Pulling images from Docker Hub or other registries - Containers trying to reach external APIs or services - Docker daemon attempting to communicate with remote hosts - Running commands like `docker login` or `docker push` Unlike DNS resolution errors (which show "could not resolve host"), this error means the hostname was resolved to an IP address, but the network path to that IP is blocked or unavailable.
First, confirm your host machine has internet access:
ping -c 3 8.8.8.8
curl -I https://registry-1.docker.ioIf these fail, the problem is with your host's network configuration, not Docker. Check your network connection, router, and firewall settings.
If you previously configured Minikube, Docker Machine, or remote Docker, the DOCKER_HOST variable might point to an unreachable address:
echo $DOCKER_HOSTIf it shows an IP address (like tcp://192.168.64.4:2376), unset it:
unset DOCKER_HOST
unset DOCKER_TLS_VERIFY
unset DOCKER_CERT_PATHAlso check and remove from your shell profile (~/.bashrc, ~/.zshrc) any lines like:
eval $(minikube docker-env)A simple restart often resolves transient network issues:
# Linux with systemd
sudo systemctl restart docker
# macOS/Windows Docker Desktop
# Use the Docker Desktop menu to restart, or:
# macOS
killall Docker && open /Applications/Docker.app
# Verify Docker is running
docker infoDocker requires IP forwarding to be enabled for container networking. Check and enable it:
# Check current setting
sysctl net.ipv4.conf.all.forwarding
# Enable temporarily
sudo sysctl -w net.ipv4.conf.all.forwarding=1
# Enable permanently
echo "net.ipv4.conf.all.forwarding=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -pThen restart Docker:
sudo systemctl restart dockerIf Docker's network bridge is corrupted, reset it:
# Stop Docker
sudo systemctl stop docker
# Remove the existing bridge
sudo ip link set docker0 down
sudo ip link delete docker0
# Restart Docker (it will recreate docker0)
sudo systemctl start docker
# Verify the bridge exists
ip addr show docker0Ensure Docker can reach DNS servers. Create or edit /etc/docker/daemon.json:
sudo nano /etc/docker/daemon.jsonAdd DNS configuration:
{
"dns": ["8.8.8.8", "8.8.4.4"]
}Restart Docker:
sudo systemctl restart dockerNote: Use your corporate DNS servers instead if public DNS is blocked.
Ensure iptables allows Docker traffic:
# Check if Docker's iptables rules exist
sudo iptables -L -n | grep -i docker
# Reset iptables NAT table (Docker will recreate rules on restart)
sudo iptables -t nat -F
sudo systemctl restart docker
# For firewalld (CentOS/RHEL/Fedora)
sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
sudo firewall-cmd --reloadIf using UFW on Ubuntu:
sudo ufw allow in on docker0 from any to anyIf your host only has IPv6 connectivity, Docker Hub's default registry may not be reachable. Use Docker's IPv6-enabled registry:
# Pull using IPv6 registry endpoint
docker pull registry.ipv6.docker.com/library/ubuntu:latestAlternatively, enable IPv6 for Docker daemon in /etc/docker/daemon.json:
{
"ipv6": true,
"fixed-cidr-v6": "fd00::/80"
}If you need IPv4 connectivity, contact your hosting provider to attach an IPv4 interface.
If running Docker inside a virtual machine:
1. Verify VM network adapter is connected and has the correct mode (NAT for internet access, or Bridged for direct network access)
2. For VirtualBox:
- Go to Settings > Network
- Ensure Adapter is attached to NAT or Bridged Adapter
- Check "Cable Connected" is enabled
3. For VMware:
- Check VM Settings > Network Adapter
- Set to NAT or Bridged mode
4. For cloud VMs (AWS, GCP, Azure):
- Verify security groups/firewall rules allow outbound HTTPS (port 443)
- Check that the instance has a public IP or NAT gateway configured
As a temporary workaround, bypass Docker's network isolation:
# Run container with host networking
docker run --network host your-image
# Or in Docker Compose
services:
your-service:
network_mode: hostWarning: This removes network isolation. Only use for debugging or when necessary.
MTU issues: If your network uses a non-standard MTU (common with VPNs, PPPoE, or certain cloud providers), Docker's default MTU of 1500 may cause problems. Configure a lower MTU in /etc/docker/daemon.json:
{
"mtu": 1400
}Rootless Docker: In rootless mode, networking uses slirp4netns which has different behavior. If experiencing network issues in rootless mode, try:
systemctl --user restart dockerWSL2 considerations: On Windows with WSL2, network issues can occur after sleep/hibernate. Restart WSL with wsl --shutdown and reopen your terminal.
Proxy environments: If behind a corporate proxy, Docker needs proxy configuration. Set HTTP_PROXY and HTTPS_PROXY either in the Docker daemon configuration or in ~/.docker/config.json:
{
"proxies": {
"default": {
"httpProxy": "http://proxy.example.com:8080",
"httpsProxy": "http://proxy.example.com:8080",
"noProxy": "localhost,127.0.0.1"
}
}
}Kubernetes context: If using Docker with Minikube or Kind, ensure the correct context is set and the cluster is running. Network unreachable errors may indicate the cluster's Docker endpoint is down.
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