Troubleshooting Connectivity Issues: Debugging Docker Networks

Previously in this course, we explored multi-container networking and how to wire services together using Docker's internal DNS. Now that your services are connected, you will inevitably encounter the "service unreachable" error; this lesson provides a systematic framework for troubleshooting, debugging, and resolving those networking failures.

The Troubleshooting Mindset

When a container cannot reach another, the issue usually falls into one of three buckets: DNS resolution (can it find the service?), Port binding (is the service actually listening?), or Network policy (is there an explicit restriction?).

Before panicking, follow the "Inside-Out" approach:

1. Check the logs of the service you are trying to reach.
2. Verify the network path from within the source container.
3. Inspect the bridge network configuration.

1. Checking Logs for Silent Failures

Often, a "network timeout" isn't a network issue at all—it’s a service that failed to start or crashed silently. If your web app can't reach your database, check the database logs first. We covered how to effectively use working with container logs previously, but for connectivity, look specifically for "Bind address already in use" or "Waiting for connection" messages.

Bash
# Check if the database service is actually running and accepting connections
docker compose logs -f <service_name>

2. Using Diagnostic Tools Within Containers

If the service logs look healthy, the next step is to test the network from inside the source container. Many minimal images (like Alpine) don't come with ping or curl pre-installed. You can install them on the fly to diagnose, or use a "debug sidecar."

For a quick test, use docker exec to run a command inside a running container:

Bash
# Enter the shell of your application container
docker exec -it <container_id> /bin/sh

# Once inside, attempt to reach the target service by its Docker service name
# If you don't have curl, use nc (netcat)
nc -zv <target_service_name> 5432

Diagnostic Table: Common Network Symptoms

3. Debugging with docker network inspect

If the containers are on different networks, they will never see each other. Docker Compose automatically creates a default bridge network, but if you have defined custom networks in your docker-compose.yml, you must ensure both services participate in the same one.

You can verify which networks your containers are attached to using:

Bash
docker network inspect <project_name>_default

Look for the Containers section in the JSON output. If your target service is missing from that list, it won't be reachable via the internal DNS name.

Hands-on Exercise: The Connectivity Loop

In your current project, attempt to intentionally break the connection between your web app and your database by changing the service name in your connection string to a dummy value.

1. Break it: Modify your application's environment variable to point to wrong-db-host.
2. Observe: Run docker compose up and watch the logs. You should see a connection timeout or DNS resolution error.
3. Debug: Enter the container using docker exec, try to ping wrong-db-host, and confirm the failure.
4. Fix: Revert the environment variable to the correct service name defined in your docker-compose.yml.

Common Pitfalls

• Binding to Localhost: A common mistake is configuring a service inside a container to listen on 127.0.0.1. Inside a container, localhost refers to the container itself, not the host machine or other containers. Always bind your services to 0.0.0.0.
• Assuming DNS is instant: If you are dynamically creating networks, DNS might take a few seconds to propagate.
• Firewall Interference: If you are running Docker on Linux, verify that your system firewall (UFW/iptables) isn't dropping packets between bridge interfaces.

FAQ

Q: My container can ping the IP address but not the service name. What's wrong? A: This is almost certainly an internal Docker DNS issue. Ensure the container is part of the user-defined network created by Compose.

Q: Can I use telnet to test connections? A: telnet is rarely installed in minimal images. nc -zv (netcat) is the industry standard for testing if a TCP port is open.

Recap

Troubleshooting is about narrowing the search space. Start by verifying the service is actually alive via logs, test the connectivity using nc or curl from within the source container, and finally, verify the network topology using docker network inspect. Mastering these steps prevents hours of frustration when dealing with complex multi-container stacks.

Up next: Scaling Services — observing how adding replicas impacts your network and service discovery.