PostgreSQL: connection refused

Client-side error (no server SQLSTATE) · Updated July 9, 2026

psql: error: connection to server at "db.example.com" (10.0.0.12), port 5432 failed: Connection refused
        Is the server running on that host and accepting TCP/IP connections?

This error is not from PostgreSQL — it never saw the connection. "Connection refused" is the operating system on the target host saying that nothing is listening on that address and port (or a firewall actively rejected the packet). That distinction immediately narrows the search.

What this error means

Three failure modes at connect time look similar but mean different things:

Symptom	Meaning
`Connection refused`	TCP reached the host, nothing listening on that port (or firewall REJECT). PostgreSQL not involved.
Connection timeout	Packets silently dropped — typically a firewall or security group, or wrong host.
`no pg_hba.conf entry for host ...`	You did reach PostgreSQL; now it's an authentication-config problem, a different page of the manual.

So "Connection refused" means: wrong place, wrong port, or no server running there.

Common causes

PostgreSQL isn't running — crashed, failed to start after a config change, or the host rebooted and the service isn't enabled.
It only listens on localhost. The default listen_addresses = 'localhost' accepts no remote TCP connections at all.
Wrong port. The server may be on a non-default port — on Debian/Ubuntu, a second cluster on the same host typically gets 5433.
Docker networking: the container port isn't published (-p 5432:5432), or you're using localhost from inside another container instead of the service name.
A firewall configured to reject (rather than drop) on that port.

How to diagnose it

From the client:

pg_isready -h db.example.com -p 5432

On the server host:

# Il servizio gira?
systemctl status postgresql

# Qualcosa ascolta, e su quale indirizzo/porta?
ss -lntp | grep -E '5432|postgres'

If the service is down, the reason for the failed start is in the logs (journalctl -u postgresql or the PostgreSQL log directory) — a typo in postgresql.conf after an edit is a classic. If it's running but bound to 127.0.0.1 only, it's listen_addresses.

How to fix it

Service down → read the startup error in the log, fix it, systemctl start postgresql (and enable it).
Remote access needed → set listen_addresses in postgresql.conf (requires a restart), add a matching pg_hba.conf rule, and open the firewall — to the specific client networks only. Exposing 5432 to the internet invites constant attack traffic; restrict by CIDR and require strong auth (scram-sha-256) and TLS.
Wrong port → check port in postgresql.conf (or the cluster listing on Debian-family systems) and fix the connection string.
Docker → publish the port, or from another container connect to the compose service name, not localhost.