Docker Network Troubleshooting

Systematic approach to diagnosing and fixing Docker networking issues.

Diagnostic Toolkit

# Essential tools
docker network ls             # list all networks
docker network inspect <net>  # detailed network info + connected containers
docker inspect <container>    # container config, IP, ports, network settings
docker logs <container>       # container stdout/stderr
docker stats                  # live resource usage

Connectivity Debugging

Step 1: Verify container is running and healthy

docker ps -a                         # check status + exit codes
docker inspect <container> | grep -A5 Health

Step 2: Check IP assignment

docker inspect <container> \
  --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'

Step 3: Test connectivity from inside

# Run a debug container on the same network
docker run --rm --network <net> nicolaka/netshoot

# Or exec into the container
docker exec -it <container> sh

# Inside: test DNS
nslookup other-service
cat /etc/resolv.conf

# Inside: test TCP
nc -zv other-service 8080
curl -v http://other-service:8080/health

Step 4: Check port mappings

docker port <container>
docker inspect <container> --format '{{json .NetworkSettings.Ports}}'

# On the host: is something listening?
ss -tlnp | grep <port>

Common Issues & Fixes

"Cannot connect to Docker daemon"

sudo systemctl status docker
sudo systemctl start docker
# Check socket permissions
ls -la /var/run/docker.sock

Container can't reach internet

# Check if forwarding is enabled on host
cat /proc/sys/net/ipv4/ip_forward   # should be 1
sysctl net.ipv4.ip_forward=1

# Check iptables FORWARD policy
iptables -L FORWARD
# If policy is DROP, Docker can't route traffic

DNS not resolving inside container

# Check if on user-defined network (default bridge has no DNS)
docker network inspect bridge
# Move container to user-defined network

# Test DNS directly
docker run --rm --network my-net busybox nslookup my-service 127.0.0.11

Port already in use

# Find what's using the port
ss -tlnp | grep :80
fuser 80/tcp
# Kill the process or change the port mapping

Overlay network: containers on different hosts can't communicate

# Check swarm status
docker node ls
docker network inspect <overlay>

# Verify VXLAN port is open (UDP 4789)
sudo iptables -L -n | grep 4789

# Check node connectivity
docker run --rm --network ingress nicolaka/netshoot ping <other-node-ip>

The nicolaka/netshoot Toolkit

A debug container with 60+ network tools:

docker run --rm -it \
  --network container:<target-container> \
  nicolaka/netshoot

# Available: tcpdump, iperf3, nmap, dig, curl, netstat, ss, traceroute, ...

# Capture traffic on a specific container's network
tcpdump -i eth0 -n port 8080

# Test bandwidth
iperf3 -c <server-ip>

# Trace route to another service
traceroute other-service

Checking iptables Rules

# All Docker-related chains
sudo iptables -t nat -L DOCKER -n --line-numbers
sudo iptables -L DOCKER-ISOLATION-STAGE-1 -n
sudo iptables -L DOCKER-USER -n

# Drop → Accept: add rule to DOCKER-USER
sudo iptables -I DOCKER-USER -s 192.168.1.0/24 -j ACCEPT

Network Inspect: What to Look For

docker network inspect my-net

Key fields:

• "Containers" — which containers are attached + their IPs
• "IPAM.Config" — subnet and gateway
• "Options" — driver-specific settings (encrypted, vxlan id, etc.)
• "Internal" — whether egress is blocked

Summary

• Start with docker network inspect and docker inspect
• Use nicolaka/netshoot for deep diagnostics from within the network namespace
• DNS issues → ensure you're on a user-defined network
• Overlay issues → check UDP 4789, swarm membership, and host connectivity
• iptables issues → check FORWARD policy and ip_forward sysctl