Researched guidance: How should an ECONNREFUSED error distinguish an absent listener from a container port mismatch?

Summary

ECONNREFUSED is a transport-level observation that a TCP stream connection to the resolved remote address and port was actively refused; it does not by itself identify whether the listener is absent because the process is down, the wrong port or address was selected, or a container/service port mapping targets the wrong destination. Diagnose from the same network namespace by comparing the exact connect target with the listener and each mapping hop.

Candidate action

Treat ECONNREFUSED as 'no listener at the exact address:port reached by this connection attempt' until the path is decomposed. Record the hostname, resolved address family and IP, port, protocol, network namespace, and whether the client is on the host, in a container, or in a Pod. From that same namespace, test the exact endpoint and inspect the listener table and owning process. For Docker, read the published mapping as HOST_PORT:CONTAINER_PORT, verify the application is listening on the container port, and use the host port only from the host-facing path; container-to-container traffic on a shared network should use the service/container name and the internal listening port. Do not treat EXPOSE as a published listener. For Kubernetes, compare the Service port with targetPort, inspect EndpointSlices, test each Pod IP at targetPort, and test the Service IP at the Service port. If direct Pod or container access is refused, the application is not listening at the expected in-namespace address:port or is unhealthy. If the direct target works but the Service or published path is refused, focus on the port mapping, selector/endpoints, address family, network namespace, proxy, or routing layer. Only call it an absent listener after the exact destination has been verified; call it a port mismatch when the listener exists at one port but the client or mapping sends traffic to another.

Applicability

• TCP clients that report ECONNREFUSED while connecting to HTTP or other stream services.
• Docker or Compose deployments where host ports are published to container ports.
• Kubernetes Services where Service port, targetPort, Pod ports, selectors, and EndpointSlices can differ.

Key findings

• Linux documents ECONNREFUSED for a stream connect when no one is listening on the remote address; this defines the immediate transport observation but not the upstream configuration cause. (S1)
• Node.js describes ECONNREFUSED as the target machine actively refusing the connection and says it usually results from connecting to an inactive service; use the stable error code rather than parsing the message. (S2)
• Docker's HOST_PORT:CONTAINER_PORT mapping forwards the host port to the container port where the application listens; EXPOSE alone does not publish a port, so a mapping must be checked against the actual in-container listener. (S3)
• Kubernetes troubleshooting separates the Service port from the Pod port, directs operators to verify targetPort, selectors, and EndpointSlices, and recommends direct Pod-IP testing to determine whether Pods are listening at the expected port. (S4)

Known limitations

• The error names the refused connect target, not the configuration mistake that led traffic there; the same code can be consistent with a stopped process, wrong address family, wrong network namespace, wrong port, or an intermediary actively rejecting the connection.
• A successful TCP connection to a listener does not prove the application protocol, route, readiness, or response is correct; continue with an application-level health check after the listener test.
• Docker and Kubernetes documentation describe their own mapping models; other runtimes, proxies, service meshes, NAT devices, and IPv4/IPv6 policies can add hops or change what is visible from the client namespace.
• This is researched guidance only: no target container, Pod, Service, process, or live connection was inspected, and no independent reproduction was performed.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• The cited documentation supports the meaning of ECONNREFUSED and the Docker/Kubernetes port-path checks; it does not establish which process, address, or mapping is failing in a particular deployment.

What remains unknown

• The target runtime, network namespace, hostname resolution result, IP family, and exact address:port that produced the error.
• Whether a process was listening in the relevant container or Pod at the configured internal port when the failure occurred.
• Whether the failing path used a Docker published port, a Kubernetes Service, a direct Pod or container address, a proxy, or another forwarding layer.
• Whether the application was ready and accepting the expected protocol after a listener was found.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 connect(2) - Linux manual page · official_documentation · accessed 2026-09-21
• S2 Errors | Node.js v26.9.0 Documentation · official_documentation · accessed 2026-09-21
• S3 Publishing and exposing ports | Docker Docs · official_documentation · accessed 2026-09-21
• S4 Debug Services | Kubernetes · official_documentation · accessed 2026-09-21