Welcome to LeviFREE's Blog

1. Three Highly Frequent Errors#

1. connection refused
2. temporary failure in name resolution
3. no route to host

These errors might look similar, but their root causes are completely different.

2. Check the Network Topology First#

1
docker compose ps
2
docker network ls
3
docker network inspect <network_name>

Goal: Confirm whether the services are in the same compose network.

3. Service Name Resolution Rules#

Within a Compose network, services should access each other via service_name:port.

Incorrect example:

• Connecting to the database B from inside container A by accessing localhost:5432.

Correct example:

• Using db:5432 (where db is the service name).

4. depends_on Does Not Mean “Service Ready”#

depends_on only guarantees the startup order; it does not guarantee that the database is ready to accept connections.

It is recommended to add health checks and retry logic:

1
services:
2
  app:
3
    depends_on:
4
      db:
5
        condition: service_healthy
6
  db:
7
    healthcheck:
8
      test: ["CMD", "pg_isready", "-U", "postgres"]
9
      interval: 5s
10
      timeout: 3s
11
      retries: 10

5. The Difference Between Port Mapping and In-Container Access#

• ports is used for “Host <-> Container” mapping.
• Inter-container access does not rely on ports; it relies on the internal network.

Many people mistakenly believe that without port mapping, containers cannot communicate with each other. This is a typical misconception.

6. Quick Diagnostic Commands#

Execute inside the container:

1
getent hosts db
2
nc -vz db 5432
3
curl -I http://api:8080

These three steps can quickly determine whether the issue lies with DNS, ports, or the service itself.

7. Common Fixes#

1. Unify services under the same user-defined network.
2. Change cross-container access addresses to service names.
3. Add health checks to dependent services.
4. Add a startup retry mechanism on the application side.

Summary#

The essence of Compose network failures is often a “faulty mental model.” As long as you thoroughly understand that “inside a container, localhost only points to itself,” you can locate 80% of cross-access problems on the first try.