Troubleshoot dial tcp: connection refused

Check processes, listening addresses, network namespaces, and firewall rejections when a TCP connection to 127.0.0.1:9443 is refused.

Guance Editorial Team 2026-10-27 4 min read Updated 2026-10-27

Best practices

Illustration of application infrastructure and operations

dial tcp 127.0.0.1:9443: connect: connection refused means the TCP connection attempt was actively rejected. Common causes include a port with no listener, the wrong address or network namespace, and an explicit firewall rejection. A timeout means the connection did not complete within the allowed time; it does not identify a particular firewall as the cause.

Work through the process, listener, network policy, and client address in that order.

1. Check whether the service is running

For a Prometheus service on a Linux host:

ps aux | grep prometheus    # Substitute your service name.
systemctl status prometheus

If it is stopped, use the service's normal start procedure, such as systemctl start prometheus. A manually managed instance might use ./prometheus --config.file=prometheus.yml. Avoid starting a duplicate process when a service manager already owns it.

2. Check its listening address and port

ss -tlnp | grep 9443

Interpret the listener in the network namespace where the service runs:

127.0.0.1:9443 listens on IPv4 loopback in that namespace. A remote host cannot reach that listener through the host's external address.
0.0.0.0:9443 listens on all local IPv4 interfaces. Routing and firewall rules still govern access.
No entry for port 9443 means you should check the configured port, service startup, and namespace. Prometheus exposes its listening address through --web.listen-address.

A loopback-only listener does not guarantee that every external attempt will report “refused”; network policy can instead cause a timeout.

3. Inspect host and cloud firewall rules

sudo iptables -L -n
sudo ufw status
# Only if remote access is required; replace with an approved source IP.
sudo ufw allow from 192.0.2.10 to any port 9443 proto tcp

The example is a narrowly scoped UFW rule, not an instruction to expose a management endpoint publicly. Cloud security groups must also permit the intended path. A silently dropped packet commonly produces a timeout, while an explicit reject can produce an immediate connection error.

4. Verify the client's destination

Confirm the port. Prometheus normally listens on 9090, not 9443, unless configured otherwise.
Confirm HTTP versus HTTPS. A protocol mismatch generally fails after TCP connects; it does not by itself explain a TCP refusal on the same address and port.
Resolve localhost in the client's namespace. Ordinary containers usually have separate network namespaces; containers in the same Kubernetes Pod share networking. Host-network mode changes those assumptions.

For example, when DataKit cannot reach an exporter, test the exporter address from DataKit's network namespace. A successful request from the host does not prove a containerized collector can reach it.

Compare common errors

Error	What it establishes	Useful next checks
Connection refused	The attempt received an active rejection; it does not prove the application host answered	Listener, destination, namespace, reject rules
Timeout	The connection did not complete in time	Packet captures, logs at both ends, route, policy, load
No route to host	A host-unreachable condition, which may also result from a network rejection	Routes, gateways, and firewall reject rules

Frequently asked questions

Why does localhost work while another machine fails?

Check whether the service is bound only to loopback. If it is, either expose the intended interface with appropriate access controls or put a reverse proxy in front of it. If the listener already covers the external interface, inspect routing and firewall rules rather than changing the bind address blindly.

How does a container reach a service on the host?

On Docker Desktop, host.docker.internal provides the host address. On Linux Docker Engine, configure a supported host-gateway mapping or use a reachable host address. For service-to-service communication, prefer the relevant Compose or Kubernetes service name. Container localhost normally refers to that container's namespace.

Everything looks correct, but the connection still fails. What next?

Check the actual resolved address, selected proxy, and namespace. Depending on the client, proxy environment variables can alter the path; configure supported no_proxy settings for localhost and 127.0.0.1 when appropriate. Also verify that you are testing the same Pod, port, and address as the failing process.