Connection Refused: What It Really Means

Connection refused sounds hostile and vague, but it's actually one of the most precise errors you'll get. It has a specific meaning, and understanding it points you straight at the fix instead of leaving you guessing.

What it actually means

"Connection refused" means your request reached the target machine, but nothing was listening on the port you tried. The machine is reachable; it actively turned you away because no program was there to answer. That's very different from a timeout (where you couldn't reach the machine at all).

The number one cause: the service isn't running

Most of the time, the program you're trying to reach simply isn't up. Check it:

ss -ltnp | grep :5432      # is anything listening on the port?

If nothing is listening, start the service — and look into why it was down.

Cause 2: It's listening on a different port

The service is running, but on a port other than the one you tried. Confirm the real port it's bound to and update what you're connecting with to match.

Cause 3: Listening on the wrong interface

A service can listen only on localhost (127.0.0.1), which means it accepts connections from the same machine but refuses ones from outside. If you're connecting remotely and it's bound to localhost only, you'll be refused. It must listen on an externally reachable address.

Reachable machine + nothing answering on that port = connection refused. Reachable machine + something answering = success. Unreachable machine = timeout, a different problem entirely.

Quick diagnosis order

1. Is the service running at all?
2. Is it listening on the port you're using?
3. Is it listening on an address you can reach (not just localhost)?

The takeaway

Don't treat "connection refused" as a mystery. It's telling you precisely: I reached the host, but no one was listening there. Find the service, confirm its port, check what address it's bound to — and the refusal turns into a connection.