Debugging network issues in Docker - Commands & Configuration

Introduction

Sometimes your Docker containers cannot talk to each other or to the internet. Debugging network issues helps you find and fix these connection problems so your apps work smoothly.

When a container cannot reach the internet to download updates or data.

When two containers on the same host cannot communicate as expected.

When a containerized app cannot connect to a database running in another container.

When you want to check if a container's network settings are correct.

When troubleshooting why a container port is not accessible from outside.

Commands

This command lists all Docker networks on your system so you can see which networks exist and their types.

Terminal

docker network ls

Expected Output

NETWORK ID     NAME      DRIVER    SCOPE

b1a2c3d4e5f6   bridge    bridge    local

c7d8e9f0a1b2   host      host      local

f3g4h5i6j7k8   none      null      local

This command shows detailed information about the default bridge network, including connected containers and IP addresses.

Terminal

docker network inspect bridge

Expected Output

[

    {

        "Name": "bridge",

        "Id": "b1a2c3d4e5f6",

        "Created": "2024-06-01T12:00:00.000000000Z",

        "Scope": "local",

        "Driver": "bridge",

        "Containers": {

            "123abc456def": {

                "Name": "my-app",

                "IPv4Address": "172.17.0.2/16"

            }

        },

        "Options": {},

        "Labels": {}

    }

]

This command runs a ping test from inside the 'my-app' container to check if it can reach the internet IP 8.8.8.8 (Google DNS).

Terminal

docker exec my-app ping -c 3 8.8.8.8

Expected Output

PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.

64 bytes from 8.8.8.8: icmp_seq=1 ttl=117 time=14.2 ms

64 bytes from 8.8.8.8: icmp_seq=2 ttl=117 time=14.0 ms

64 bytes from 8.8.8.8: icmp_seq=3 ttl=117 time=13.9 ms



--- 8.8.8.8 ping statistics ---

3 packets transmitted, 3 received, 0% packet loss, time 2002ms

rtt min/avg/max/mdev = 13.900/14.033/14.200/0.130 ms

→

-c 3 - Send only 3 ping packets to limit test duration

This command tests if the 'my-app' container can reach another container named 'my-db' by pinging its hostname.

Terminal

docker exec my-app ping -c 3 my-db

Expected Output

PING my-db (172.18.0.3) 56(84) bytes of data.

64 bytes from 172.18.0.3: icmp_seq=1 ttl=64 time=0.12 ms

64 bytes from 172.18.0.3: icmp_seq=2 ttl=64 time=0.10 ms

64 bytes from 172.18.0.3: icmp_seq=3 ttl=64 time=0.11 ms



--- my-db ping statistics ---

3 packets transmitted, 3 received, 0% packet loss, time 2002ms

rtt min/avg/max/mdev = 0.100/0.110/0.120/0.010 ms

→

-c 3 - Send only 3 ping packets to limit test duration

This command shows the logs of the 'my-app' container to check for any network-related error messages.

Terminal

docker logs my-app

Expected Output

Connecting to database at my-db:5432...

Connection successful.

Starting web server on port 8080.

Key Concept

If you remember nothing else from this pattern, remember: checking network connectivity inside containers with ping and inspecting Docker networks helps find where communication breaks.

Common Mistakes

Trying to ping a container by IP without knowing the correct network or IP address.

Containers can have different IPs on different networks, so the ping will fail if the IP is wrong or the container is on another network.

Use 'docker network inspect' to find the correct IP or ping by container name if containers share a user-defined network.

Assuming the default bridge network allows container name resolution.

The default bridge network does not support automatic DNS for container names, so pinging by name fails.

Create and connect containers to a user-defined bridge network to enable name resolution.

Not checking container logs for network errors.

Network problems often show error messages in logs that help diagnose the issue.

Always check container logs with 'docker logs' to find clues about network failures.

Summary

Use 'docker network ls' and 'docker network inspect' to understand Docker networks and container connections.

Run 'docker exec <container> ping' commands to test connectivity inside containers to IPs or other containers.

Check container logs with 'docker logs' to find network-related error messages.