Docker Container Networking Issues on Linux: Debugging Guide

Introduction

Docker networking on Linux is powerful but complex. When containers cannot reach each other, cannot resolve DNS names, or cannot access the host network, debugging requires understanding Docker's network namespaces, iptables rules, and virtual interfaces. This post covers the most common Docker networking issues on Linux and how to resolve them systematically.

Environment

The examples use Docker 24.0.7 on Ubuntu 22.04 LTS with the default bridge network driver. The system runs several containers that need to communicate with each other and the host.

docker --version
# Docker version 24.0.7, build afdd53b

docker network ls
# NETWORK ID     NAME      DRIVER    SCOPE
# 123456789012   bridge    bridge    local
# 987654321098   host      host      local
# 456789012345   none      null      local

Problem

A container cannot resolve DNS names:

docker run --rm alpine ping google.com
# ping: bad address 'google.com'

Or containers cannot communicate:

docker run -d --name web nginx
docker run --rm alpine ping web
# ping: bad address 'web'

Or port mapping does not work:

docker run -d -p 8080:80 nginx
curl localhost:8080
# curl: (7) Failed to connect to localhost port 8080: Connection refused

Analysis

Docker networking involves several layers:

Network namespaces: Each container gets its own network stack
Virtual Ethernet pairs (veth): Connect container to bridge
Bridge (docker0): Connects containers on the same network
iptables: Handles port mapping and NAT
DNS: Docker's embedded DNS server (127.0.0.11)

Check the current network configuration:

# View docker0 bridge
ip addr show docker0
# docker0:  mtu 1500
#     inet 172.17.0.1/16 scope global docker0

# View container network namespace
docker inspect web --format '{{.NetworkSettings.Networks}}'
# map[bridge:0xc000123456]

# Check DNS configuration inside container
docker exec web cat /etc/resolv.conf
# nameserver 127.0.0.11
# options ndots:0

Solution

1. Fix DNS resolution issues

Check if Docker daemon is using the host DNS:

# Check Docker daemon DNS configuration
cat /etc/docker/daemon.json
# {
#   "dns": ["8.8.8.8", "8.8.4.4"]
# }

# If missing, add DNS servers
sudo nano /etc/docker/daemon.json
# {
#   "dns": ["8.8.8.8", "8.8.4.4"]
# }

sudo systemctl restart docker

2. Enable container-to-container DNS resolution

Use user-defined networks instead of the default bridge:

# Create a custom network
docker network create mynetwork

# Run containers on the custom network
docker run -d --name web --network mynetwork nginx
docker run -d --name api --network mynetwork node:alpine

# Now containers can resolve each other by name
docker exec api ping web
# PING web (172.18.0.2): 56 data bytes

3. Fix port mapping issues

Check if ports are already in use:

# Check port usage
ss -tlnp | grep 8080
# If another process is using the port, stop it or use a different port

# Verify Docker port mapping
docker port web
# 80/tcp -> 0.0.0.0:8080

# Check iptables rules
sudo iptables -t nat -L -n | grep 8080
# DNAT tcp -- 0.0.0.0/0 0.0.0.0/0 tcp dpt:8080 to:172.17.0.2:80

4. Fix host network access

# Use host network mode (shares host's network namespace)
docker run --network host nginx
# Container uses host's IP and ports directly

# Check if host.docker.internal works (Docker Desktop)
docker run --rm alpine ping host.docker.internal

# For Linux, use --add-host
docker run --add-host=host.docker.internal:host-gateway nginx

5. Debug network namespace

# Enter container's network namespace
docker exec -it web sh

# Inside container, check network interfaces
ip addr show
# 1: lo: 
#     inet 127.0.0.1/8
# 15: eth0@if16: 
#     inet 172.17.0.2/16

# Check routing table
ip route
# default via 172.17.0.1 dev eth0

6. Fix inter-container communication on default bridge

# Enable inter-container communication (default: true)
# /etc/docker/daemon.json
# {
#   "icc": true
# }

# Or use --link (deprecated but still functional)
docker run -d --name web nginx
docker run --rm --link web:web alpine ping web

7. Debug with network utilities

# Install network tools in container
docker run --rm -it alpine sh -c "apk add --no-cache curl bind-tools"

# Test DNS resolution
docker exec web nslookup google.com
# Server:    127.0.0.11
# Address 1: 127.0.0.11

# Test connectivity
docker exec web curl -v http://api:3000/health

8. Check Docker daemon logs

sudo journalctl -u docker.service | tail -50
# Look for network-related errors

# Restart Docker daemon
sudo systemctl restart docker

9. Reset Docker networking

# Stop all containers
docker stop $(docker ps -q)

# Remove all containers and networks
docker system prune -af

# Restart Docker
sudo systemctl restart docker

10. Use Docker Compose for complex networking

# docker-compose.yml
version: '3.8'
services:
  web:
    image: nginx
    ports:
      - "8080:80"
    networks:
      - frontend

  api:
    image: node:alpine
    ports:
      - "3000:3000"
    networks:
      - frontend
      - backend

  db:
    image: postgres:16
    networks:
      - backend

networks:
  frontend:
  backend:
    driver: bridge

docker-compose up -d
# Containers in the same network can communicate by name

11. Monitor network traffic

# Capture traffic on docker0
sudo tcpdump -i docker0 -n

# Check container network stats
docker stats --no-stream
# CONTAINER ID   NAME   CPU %   MEM USAGE / LIMIT
# 1234567890ab   web    0.01%   5.234MiB / 128MiB

Lessons Learned

Docker networking issues are almost always caused by DNS resolution or network isolation. Use user-defined networks instead of the default bridge for proper DNS resolution between containers. For debugging, enter the container's network namespace with docker exec and use standard network tools. And always check Docker daemon logs with journalctl when networking behaves unexpectedly.

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.