Docker / Editorial solution guide

Container networking: trace the caller to the listener

Separate namespace, DNS, listener, publication, and HTTP behavior before changing exposure.

About 4 min readContent reviewed

Read-only knowledge base ยท No public comments

Recognize the symptoms

A host browser cannot connect to the published API, or a peer container receives connection refused when using localhost. A name-resolution error, timeout, and HTTP 404 are different observations, not interchangeable evidence of a firewall problem.

EXPOSE 8080 is present in the image, yet no intended host listener exists. Another symptom is a client incorrectly targeting the host-published port as if it were the internal service port.

Understand the likely causes

  • Each normal container has its own loopback namespace. localhost in a worker refers to that worker. EXPOSE is image metadata; an application listener and a host port mapping are separate requirements.
  • Services may not share the intended network, the application may bind only its own loopback, or the mapping may target the wrong container port. A cached container IP can become stale after replacement.

Identify where the request starts

Use the synthetic parcel-api contract: the process listens at 0.0.0.0:8080 inside its container. A host consumer and a same-network service need different destination forms. Record the caller location, exact URL, transport, and error before editing Compose. Do not widen an address to every host interface simply because the current path is not understood.

text Declared teaching traffic paths 
Host caller: http://127.0.0.1:18080/
Same-network peer: http://api:8080/
Container listener: 0.0.0.0:8080

These paths assume the loopback mapping and shared Compose network described below. They are not measured reachability results. A remote machine cannot use the host's loopback address as if it were its own connection to the service.

Inspect publication and membership separately

Use the approved project and context to discover actual service containers, then inspect the effective published mapping and network membership. The following commands are read-only diagnostic examples and are not executed here. A correct mapping still does not prove that the application is accepting requests. Generated names depend on project configuration, so the network example assumes project parcel-lab and its default network.

bash Read runtime routing evidence 
docker compose ps --all
docker compose port api 8080
docker network inspect parcel-lab_default

ps identifies instances and state; port reports host publication; network inspect identifies attached endpoints. Redact infrastructure details before sharing. No fixed IP, generated container id, or successful connection is fabricated, and no firewall or network is changed.

Align the three independent port settings

For the fixture, use a listener at container port 8080 and a deliberately loopback-scoped publication to host port 18080. A same-network peer should use api:8080, not localhost:18080. The following complete model assumes the earlier lab image exists and does not start it. If the process actually binds 127.0.0.1 inside the container, correct that application binding through a reviewed configuration change; publishing alone cannot repair it.

yaml Explicit host mapping for the fixture 
name: parcel-lab
services:
  api:
    image: parcel-api:lab
    ports:
      - "127.0.0.1:18080:8080"

The left address and port belong to the host publication; the right port belongs to the container. No external exposure or TLS termination is implied. The model does not require publishing every internal dependency, and it is not proof of deployment or endpoint readiness.

Interpret the response layer accurately

DNS failure means the name was not resolved from that caller. Refused indicates a reached endpoint rejected the connection; timeout can involve filtering, routes, or a nonresponsive destination. HTTP 404 means an HTTP server answered and the requested route needs investigation. An internally healthy process can coexist with a wrong external mapping. Use those distinctions to choose the next narrow check rather than restarting every service.

Verify the fix

Verify a bounded request from the actual intended consumer path in a separately approved lab. For the declared fixture, a successful response body is parcel-api followed by a newline; headers and timing vary. Confirm the host binding remains intentionally scoped and same-network clients use service discovery, then test replacement without hardcoded IP assumptions.

Keep it from recurring

  • Document internal and host URLs, avoid hardcoded container IPs, keep listener configuration explicit, and review effective port mappings after Compose merges. Validate native Linux, Desktop, and rootless behavior on their actual target rather than assuming identical host routing.

Official references