How to fix dial tcp: connect: network is unreachable in Docker

DockerINTERMEDIATEMEDIUMUpdated Aug 8, 2026· 516 views

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.

Quick fix

Fixes dial tcp: connect: network is unreachable

ping -c 3 8.8.8.8
curl -I https://registry-1.docker.io
  1. Verify host internet connectivity
  2. Check and reset DOCKER_HOST environment variable
  3. Restart Docker daemon
  4. Enable IP forwarding
docker — error
ping -c 3 8.8.8.8
curl -I https://registry-1.docker.io
dial tcp: connect: network is unreachable

What this error means

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.

Typical symptoms

  • docker pull fails with 'dial tcp x.x.x.x:443: connect: network is unreachable'
  • docker push or docker login fails with network unreachable error
  • Containers cannot reach external APIs or services
  • Error appears after system reboot or network configuration changes
  • Works with --network host but fails with default bridge network
  • CI/CD pipelines fail during Docker image pull/push steps
  • Error contains specific IP address that cannot be reached

Common causes

  1. Docker host has no default network route (no internet connection)
  2. IPv6-only network trying to reach IPv4 addresses (or vice versa)
  3. DOCKER_HOST environment variable pointing to unreachable address
  4. Docker bridge network (docker0) not properly configured
  5. Firewall or iptables rules blocking outbound traffic from Docker
  6. VPN disconnected or misconfigured, breaking network routes
  7. Virtual machine network adapter not connected or misconfigured
  8. IP forwarding disabled on the host system
  9. Docker daemon DNS settings pointing to unreachable DNS servers
  10. MTU mismatch between Docker network and host network

How to fix "dial tcp: connect: network is unreachable"

1Verify host internet connectivity

First, confirm your host machine has internet access:

bash
ping -c 3 8.8.8.8
curl -I https://registry-1.docker.io

If these fail, the problem is with your host's network configuration, not Docker. Check your network connection, router, and firewall settings.

2Check and reset DOCKER_HOST environment variable

If you previously configured Minikube, Docker Machine, or remote Docker, the DOCKER_HOST variable might point to an unreachable address:

bash
echo $DOCKER_HOST

If it shows an IP address (like tcp://192.168.64.4:2376), unset it:

bash
unset DOCKER_HOST
unset DOCKER_TLS_VERIFY
unset DOCKER_CERT_PATH

Also check and remove from your shell profile (~/.bashrc, ~/.zshrc) any lines like:

bash
eval $(minikube docker-env)
3Restart Docker daemon

A simple restart often resolves transient network issues:

bash
# 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 info
4Enable IP forwarding

Docker requires IP forwarding to be enabled for container networking. Check and enable it:

bash
# 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 -p

Then restart Docker:

bash
sudo systemctl restart docker
5Reset Docker network bridge

If Docker's network bridge is corrupted, reset it:

bash
# 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 docker0
6Configure DNS in Docker daemon

Ensure Docker can reach DNS servers. Create or edit /etc/docker/daemon.json:

bash
sudo nano /etc/docker/daemon.json

Add DNS configuration:

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

Restart Docker:

bash
sudo systemctl restart docker

Note: Use your corporate DNS servers instead if public DNS is blocked.

7Fix firewall and iptables rules

Ensure iptables allows Docker traffic:

bash
# 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 --reload

If using UFW on Ubuntu:

bash
sudo ufw allow in on docker0 from any to any
8Handle IPv6-only networks

If your host only has IPv6 connectivity, Docker Hub's default registry may not be reachable. Use Docker's IPv6-enabled registry:

bash
# Pull using IPv6 registry endpoint
docker pull registry.ipv6.docker.com/library/ubuntu:latest

Alternatively, enable IPv6 for Docker daemon in /etc/docker/daemon.json:

json
{
  "ipv6": true,
  "fixed-cidr-v6": "fd00::/80"
}

If you need IPv4 connectivity, contact your hosting provider to attach an IPv4 interface.

9Check VM network configuration

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

10Use host network mode as workaround

As a temporary workaround, bypass Docker's network isolation:

bash
# Run container with host networking
docker run --network host your-image

# Or in Docker Compose
services:
  your-service:
    network_mode: host

Warning: This removes network isolation. Only use for debugging or when necessary.

Advanced notes

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:

json
{
  "mtu": 1400
}

Rootless Docker: In rootless mode, networking uses slirp4netns which has different behavior. If experiencing network issues in rootless mode, try:

bash
systemctl --user restart docker

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

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.

Frequently asked questions

What does "dial tcp: connect: network is unreachable" mean?
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.
How do I fix "dial tcp: connect: network is unreachable"?
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.
What causes "dial tcp: connect: network is unreachable"?
Docker host has no default network route (no internet connection) IPv6-only network trying to reach IPv4 addresses (or vice versa) DOCKER_HOST environment variable pointing to unreachable address
Is the "dial tcp: connect: network is unreachable" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading