About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
In current PostgreSQL clients the error reads connection to server at "192.0.2.20", port 5432 failed: Connection refused, followed by Is the server running on that host and accepting TCP/IP connections?. The TCP connection was turned away before PostgreSQL could ask for a password. Three things produce it: the server is not running, it is not listening on the address or port the client used, or something on the path refused the connection. The default for listen_addresses is localhost, so a new server answers TCP/IP connections only on the machine itself (Unix socket connections are separate).
What the error means
The message comes from the client library, libpq, not from the server. In the PostgreSQL source (REL_17_STABLE and REL_19_STABLE), libpq builds the start of the message as connection to server at "%s", port %s failed: , or connection to server at "%s" (%s), port %s failed: when the host name resolved to a different address. It then appends the operating system's error text. For a socket connection the start is connection to server on socket "%s" failed: . After the error text the library adds a hint line: Is the server running on that host and accepting TCP/IP connections? for a network connection, or Is the server running locally and accepting connections on that socket? for a local socket.
Older releases word it differently. The REL_13_STABLE source (the PostgreSQL versioning page lists version 13 as no longer supported, final release 13.23, 13 November 2025) builds could not connect to server: %s and then Is the server running on host "%s" and accepting TCP/IP connections on port %s? split over lines. Searches for the older wording lead here too.
The error text is the operating system's. The Linux errno(3) page gives ECONNREFUSED as "Connection refused", ETIMEDOUT as "Connection timed out", EHOSTUNREACH as "Host is unreachable", and ENOENT as "No such file or directory". They point to different faults. The page gives only these names and texts. "Connection refused" means a refusal came back. "Connection timed out" means nothing came back, which is a different investigation. "No such file or directory" with a socket path means the socket file is not there.
The PostgreSQL documentation sets the server side. listen_addresses is "the TCP/IP address(es) on which the server is to listen for connections from client applications". "The default value is localhost, which allows only local TCP/IP “loopback” connections to be made", and the parameter "can only be set at server start". port is "5432 by default", also set only at start. The hba records come after: a client that gets through still needs a matching record.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
| Server not running | Refused from every host, including the server itself | pg_ctl status, or the service manager's status for the PostgreSQL service |
listen_addresses is localhost (the default) |
Works on the server, refused from other hosts | SHOW listen_addresses; over the local socket; ss -ltn shows only 127.0.0.1 |
| Server on another port | Refused on 5432 only | SHOW port;, and the port in ss output |
| Client aims at the wrong host or port | The host or port in the message is not the server's | Compare the message with the server's address |
| A device between client and server refuses the connection | Refused from some hosts only; ss shows the server listening on the right address |
Test from the server itself, then from a host on the same network |
| Unix socket path differs | Socket variant of the message, No such file or directory |
SHOW unix_socket_directories; |
Prove the cause before changing anything
All of these are read-only.
1. Is the server answering at all? pg_isready is documented as a check of the connection status of a server. Its exit status is "0 to the shell if the server is accepting connections normally, 1 if the server is rejecting connections (for example during startup), 2 if there was no response to the connection attempt, and 3 if no attempt was made". Run it from the client host:
pg_isready -h 192.0.2.20 -p 5432
-h names the host and -p the port. The page notes you need no valid user or database to get the server status.
2. What is listening, and on which address? On the server:
ss -ltnp
The ss page documents -l (listening sockets), -t (TCP), -n (numeric) and -p (the processes using sockets). Look for the PostgreSQL port. A line on 127.0.0.1:5432 means loopback only. A line on 0.0.0.0:5432 or the server's own address means it listens on the network.
3. What the server is configured for. Connect locally (over the Unix socket) and run:
SHOW listen_addresses;
SHOW port;
SHOW unix_socket_directories;
The documentation says a local socket file is named .s.PGSQL.nnnn, where nnnn is the port, in each unix_socket_directories directory.
4. Is the process up? pg_ctl status -D datadir reports whether a server is running in that data directory. The page says status mode returns exit status 3 if the server is not running. Use your service manager's status command as well; the unit name depends on the package.
5. Test from the server and from a second host. If pg_isready succeeds on the server but fails from the client, and ss shows the server listening on the network address, the refusal is on the path (a firewall or routing), which is not covered here.
Fix
Server stopped
Disruptive step: starting a database server makes it available to clients, so check the log first and start it only when you know why it stopped. Read the server log for the reason it stopped, then start it with your service manager or pg_ctl start -D datadir. To back out, stop it the same way.
listen_addresses is localhost
Save first: print the setting and find the file.
SHOW listen_addresses;
SHOW config_file;
Copy the file named by config_file, for example cp /srv/pgdata/postgresql.conf /srv/pgdata/postgresql.conf.saved-20261120 (an example path). Edit listen_addresses. The documentation says the value is a comma-separated list of host names or numeric addresses, with * for all interfaces, and that the entry 0.0.0.0 listens on all IPv4 addresses. Prefer the server's own address, for example listen_addresses = 'localhost,192.0.2.20', over *. Then read what the server makes of the file without applying it:
SELECT sourcefile, sourceline, name, setting, applied, error FROM pg_file_settings WHERE name = 'listen_addresses';
The pg_file_settings view reports on the current contents of the files. The documentation also says that if an individual setting cannot be applied, for example because the setting cannot be changed after server start, the row "will have an appropriate message in the error field". The page does not give the wording of that message. listen_addresses can only be set at server start, so on a running server the error column may show a message for the changed line. Check that setting shows the value you typed and that sourcefile and sourceline point at the line you edited. A wrong value in setting means the edit is wrong. The restart is what applies it.
Disruptive step: listen_addresses can only be set at server start, so you must restart. pg_ctl restart is a stop followed by a start, and in its default fast mode "All active transactions are rolled back and clients are forcibly disconnected". Schedule a window. Risk: the server now accepts connections on a network interface. Add only the pg_hba.conf records you need, and limit access at the network level. If you do not set the matching record, a client reaches the server and is then rejected with the message in "PostgreSQL "no pg_hba.conf entry for host": write the rule that matches, then reload". To back out, run cp /srv/pgdata/postgresql.conf.saved-20261120 /srv/pgdata/postgresql.conf, check with the pg_file_settings query above that setting shows the old value and sourceline points at the restored line, and restart again.
Wrong port or client target
Correct the client's host or port. The PGHOST and PGPORT environment variables behave like the host and port connection parameters, so a stale variable can aim a client at the wrong place.
Unix socket path
Point the client at the directory named in unix_socket_directories. For pg_isready, the -h option does this: its page says a host value that begins with a slash "is used as the directory for the Unix-domain socket".
Example (illustrative): A new server db01 (192.0.2.20) is up, but app01 reports connection to server at "192.0.2.20", port 5432 failed: Connection refused. On db01, ss -ltnp shows PostgreSQL on 127.0.0.1:5432 only, and SHOW listen_addresses; returns localhost. The administrator saves postgresql.conf, sets listen_addresses = 'localhost,192.0.2.20', reads the entry in pg_file_settings (the right setting, on the line just edited), and restarts in the maintenance window. ss now shows a listener on 192.0.2.20, and pg_isready from app01 reports that the server is accepting connections. The next error from app01 is no pg_hba.conf entry, which is a separate fix.
Confirm the fix
ss -ltnpon the server shows PostgreSQL on the intended address and port.pg_isready -h 192.0.2.20 -p 5432from the client returns exit status 0.- The application connects, or moves on to the next error (authentication), which is progress.
- No other service lost access after the restart.
What to watch afterwards
- Monitor the port from a second host, not only from the server.
- Alert when the PostgreSQL service stops, and keep the reason in its log.
- Keep
listen_addressesin configuration management. - Re-check it after major upgrades, in case the file in use is not the one you edited.
Read next
Related articles you may want next.
- TroubleshootingPostgreSQL "no pg_hba.conf entry for host": write the rule that matches, then reloadPostgreSQL 'no pg_hba.conf entry for host'? Read the host, user, database and encryption in the message, add a matching record, check it, then reload.Read article
- Troubleshootingfirewalld rules gone after reboot or reload: runtime versus permanentfirewall-cmd rules vanish after a reload or reboot because they were runtime only. Compare runtime and permanent lists, add --permanent and reload safely.Read article
- Troubleshootingbind() to 0.0.0.0:80 failed (98: Address already in use): nginx or Apache will not startnginx or Apache will not start: bind() to 0.0.0.0:80 failed (98: Address already in use). Find the process holding the port with ss and fix the conflict.Read article
Risks and limits
- These commands have not been run or lab-tested.
- Firewall behaviour, routing and cloud security groups are not covered.
- Message text is from REL_13_STABLE, REL_17_STABLE and REL_19_STABLE source. The prefix a client tool adds before libpq's message is not covered, so only libpq's text is quoted.
- Service names and data directory paths differ between distributions.
Sources
- PostgreSQL 19: Connection Settings — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: pg_isready — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: pg_ctl — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: pg_file_settings — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: File Locations — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: Environment Variables — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: SHOW — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL REL_19_STABLE source: fe-connect.c — PostgreSQL project, branch REL_19_STABLE, no date shown, accessed 20 November 2026
- PostgreSQL REL_17_STABLE source: fe-connect.c — PostgreSQL project, branch REL_17_STABLE, no date shown, accessed 20 November 2026
- PostgreSQL REL_13_STABLE source: fe-connect.c — PostgreSQL project, branch REL_13_STABLE, no date shown, accessed 20 November 2026
- PostgreSQL versioning policy — PostgreSQL project, table lists version 13 as no longer supported (final release 13.23, November 13, 2025), accessed 20 November 2026
- errno(3) — Linux man-pages 6.19, 2026-05-28, accessed 20 November 2026
- ss(8) — iproute2 manual page on man7.org, colophon: obtained 2026-08-04, most recent upstream commit 2026-07-28, HTML rendering created 2026-09-09, accessed 20 November 2026
- cp(1) — GNU coreutils 9.11, April 2026, accessed 20 November 2026
This article was originally published on .