Docker Network Issues: Diagnose Inter-Container and DNS Failures

Docker Networking Architecture and Common Failure Points

Understanding where Docker networking can fail requires knowing the basic architecture. By default, Docker creates a bridge network (‘docker0’ / ‘bridge’). Each container on a user-defined bridge network gets a DNS name equal to its container name, resolvable by other containers on the same network. The default bridge (docker0) does NOT provide DNS resolution between containers — this is the most common source of confusion.

Key networking rules:

1. Containers must be on the same network to communicate — two containers on different networks cannot communicate directly. Check network membership with ‘docker inspect –format={{.NetworkSettings.Networks}}’.

2. The default bridge does not support DNS resolution — containers on the default ‘bridge’ network can only communicate by IP, not by container name. Use user-defined bridge networks for name-based resolution.

3. Port publishing (-p) binds the port on the host, not inside the network — other containers should connect using the internal port and container name, not the published host port. Connecting container-to-container via the host port is inefficient and can break in some network configurations.

4. iptables rules control routing — Docker manipulates iptables to create NAT rules for port publishing and routing between networks. Flushing iptables or running firewall management tools (ufw, firewalld) can break Docker networking silently.

Diagnosing Docker Network Problems

# Step 1: List all networks and see which containers are on them
docker network ls
docker network inspect <network-name>

# Step 2: Check which networks a specific container belongs to
docker inspect <container> --format='
{{range $name, $net := .NetworkSettings.Networks}}
Network: {{$name}} IP: {{$net.IPAddress}}
{{end}}'

# Step 3: Test connectivity between containers
# (ping container2 from container1)
docker exec container1 ping -c3 container2
# If ping fails, test by IP:
docker exec container1 ping -c3 <container2-ip>

# Step 4: Test DNS resolution inside the container
docker exec container1 nslookup container2
docker exec container1 cat /etc/resolv.conf

# Step 5: Test a TCP connection to a specific port
docker exec container1 nc -zv container2 5432
# Or with curl for HTTP services:
docker exec container1 curl -v http://container2:8080/health

# Step 6: Check host-level port mapping
docker port <container>
# Or:
docker inspect <container> --format='{{.NetworkSettings.Ports}}'

The critical diagnostic step is distinguishing between three failure modes: (a) ping by name fails but ping by IP succeeds — DNS issue, containers are on default bridge or different user-defined networks; (b) ping by IP also fails — containers are on different networks with no route between them; (c) ping succeeds but TCP connection fails — the application is not listening on the port, is bound to 127.0.0.1 inside the container, or a firewall rule is blocking. Each failure mode has a different fix.

Network Types and Their Connectivity Rules

Fixing Common Docker Network Problems

Containers Cannot Resolve Each Other by Name

The most common Docker networking issue: two containers cannot reach each other by container name. This is almost always because they are on the default bridge network instead of a user-defined bridge network. The fix is to create a user-defined network and attach both containers to it.

# Create a user-defined bridge network
docker network create app-network

# Start containers on the same network
docker run -d \
  --name backend \
  --network app-network \
  backend:latest

docker run -d \
  --name frontend \
  --network app-network \
  frontend:latest

# Now frontend can reach backend by name:
docker exec frontend curl http://backend:3000/api

# Connect an existing container to a network (without restart)
docker network connect app-network existing-container

# In Docker Compose (automatic network creation):
services:
  frontend:
    image: frontend:latest
    networks:
      - app-network
  backend:
    image: backend:latest
    networks:
      - app-network
networks:
  app-network:
    driver: bridge

Published Port Not Accessible from Outside the Host

When a container port is published with ‘-p’ but not reachable from external clients, the issue is usually the host firewall (ufw, firewalld, or iptables rules) blocking the port, or the port is bound to 127.0.0.1 on the host instead of 0.0.0.0.

# Check how the port is bound on the host
docker port myapp 8080
# Output: 0.0.0.0:8080 -> good (accessible externally)
# Output: 127.0.0.1:8080 -> only accessible from localhost

# Re-run with correct port binding
docker run -d \
  -p 0.0.0.0:8080:8080 \
  --name myapp \
  myapp:latest

# Check host-level iptables rules for the port
sudo iptables -t nat -L DOCKER -n --line-numbers
sudo iptables -L INPUT -n --line-numbers | grep 8080

# If ufw is blocking it:
sudo ufw allow 8080/tcp
sudo ufw status

# Verify the port is actually listening on the host
ss -tulpn | grep :8080

# Test connectivity from outside
curl -v http://<host-ip>:8080/

Diagnosing and Fixing iptables Conflicts

Docker manages iptables rules automatically. Running other firewall management tools (ufw, firewalld) can overwrite or conflict with Docker’s rules, breaking container networking without any Docker-level error.

# Check Docker's iptables rules
sudo iptables -t nat -L -n
sudo iptables -L DOCKER-USER -n

# If iptables rules are broken, restart Docker daemon to recreate them
sudo systemctl restart docker

# Permanent fix for ufw/Docker conflicts:
# Configure ufw to not manage Docker's iptables
# In /etc/default/docker or /etc/docker/daemon.json:
# { "iptables": false }  <- disables Docker iptables management
# WARNING: this requires manual routing rules if used

# Safer: use DOCKER-USER chain for custom rules
# (persists across Docker restarts)
sudo iptables -I DOCKER-USER -i eth0 -j DROP
sudo iptables -I DOCKER-USER -s 10.0.0.0/8 -j RETURN

# Check if Docker daemon has iptables enabled
docker info | grep iptables

Network Security in Docker

Practical Examples

Multi-Tier Network Isolation Setup

# Create isolated networks per tier
docker network create frontend-net
docker network create backend-net
# backend-net is internal: containers cannot reach the internet
docker network create --internal db-net

# Reverse proxy: only on frontend-net
docker run -d \
  --name nginx \
  --network frontend-net \
  -p 0.0.0.0:80:80 \
  -p 0.0.0.0:443:443 \
  nginx:stable-alpine

# App server: on frontend-net AND backend-net
docker run -d \
  --name app \
  --network frontend-net \
  app:latest
docker network connect backend-net app

# Database: ONLY on backend db-net (internal, no internet)
docker run -d \
  --name postgres \
  --network db-net \
  -e POSTGRES_PASSWORD=secret \
  postgres:16-alpine
docker network connect db-net app

# Verify network isolation:
# nginx can reach app (both on frontend-net)
# app can reach postgres (both on db-net)
# nginx CANNOT reach postgres (not on db-net)
# postgres CANNOT reach the internet (internal network)

This three-tier network isolation is the recommended pattern for web application stacks. The reverse proxy has no database access. The database is on an internal network with no outbound internet connectivity. The application server bridges the tiers but the other services cannot cross tier boundaries. This limits blast radius if any tier is compromised.

Quick Reference: Key Commands and Options

# Inspect current configuration
docker inspect <container> --format='{{json .HostConfig}}' | python3 -m json.tool

# View container resource usage
docker stats <container> --no-stream

# Check container logs
docker logs <container> --tail 50 --timestamps

# Verify running processes inside container
docker exec <container> ps aux

# Check container environment variables
docker exec <container> env | sort

These diagnostic commands work across all container scenarios: ‘docker inspect’ shows the full HostConfig including all runtime parameters, ‘docker stats’ shows real-time resource consumption, and ‘docker logs’ shows output from the main process. Use these as the starting point for any container investigation before diving into more specific tooling.

Network Troubleshooting Reference

Most Network Issues Come Down to Network Membership

The majority of Docker inter-container networking issues have a single root cause: containers are not on the same user-defined bridge network. Creating a named network and assigning containers to it enables DNS resolution by container name and direct connectivity. The default bridge network should be avoided in production — it offers no DNS, no isolation, and no fine-grained control. Published port accessibility issues are almost always iptables or host firewall configuration — ‘docker port’ and ‘ss -tulpn’ confirm what is actually bound on the host.

• Always use user-defined bridge networks (not the default bridge) for inter-container communication. User-defined bridges provide automatic DNS resolution by container name, which the default bridge does not.
• When testing container connectivity, test in order: ping by name (DNS), ping by IP (routing), then nc/curl to the specific port (application + firewall). Each level of failure points to a different root cause.
• Published ports are bound to 0.0.0.0 by default — all network interfaces including public ones. Bind to 127.0.0.1 for services that should only be accessed through a reverse proxy: ‘-p 127.0.0.1:8080:8080’.