Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Cannot connect to PostgreSQL on port 5432 from another machine

Errorpsql: error: connection to server at "203.0.113.10", port 5432 failed: Connection refused

Short answer

Two settings guard remote access. listen_addresses defaults to localhost, so the server ignores other machines until you change it and restart. After that, pg_hba.conf needs a host line for the client address, or you get no pg_hba.conf entry. Test with pg_isready from the client.

  • Applies to PostgreSQL 16, PostgreSQL 17, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    From the client, check whether anything answers on that host and port. Exit code 2 means no response, 1 means the server is up but rejecting.

    pg_isready -h 203.0.113.10 -p 5432; echo "exit code: $?"
  2. 2Match what you see, then jump to its fix

    1. 1Connection refused from remote hosts while a local psql worksThe server only listens on localhostFix
    2. 2FATAL: no pg_hba.conf entry for host ...pg_hba.conf has no line for the clientFix
    3. 3Nothing answers on 5432, but the server is runningThe server uses another port, or the client uses the wrong hostFix

What does the error look like?

  • psql: error: connection to server at "203.0.113.10", port 5432 failed: Connection refused
  • FATAL: no pg_hba.conf entry for host "198.51.100.7", user "app", database "appdb"

Cause 1 of 3

The server only listens on localhost

1Check

listen_addresses defaults to localhost, which allows only loopback TCP connections. Connection refused means nothing is listening on that address, not that the server turned you away.

sudo -u postgres psql -c "SHOW listen_addresses"
sudo ss -ltn | grep 5432

2Fix

Set listen_addresses to the interface address (or '*') in postgresql.conf. This setting only takes effect at server start, so restart.

# postgresql.conf
listen_addresses = 'localhost,203.0.113.10'

sudo systemctl restart postgresql

3Verify

ss now shows 5432 on the new address.

sudo ss -ltn | grep 5432

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 3

pg_hba.conf has no line for the client

1Check

The server was reached but no record matched the client address, user and database, and with no match access is denied. The first matching line wins.

sudo -u postgres psql -c "SELECT line_number, type, database, user_name, address, auth_method FROM pg_hba_file_rules"

2Fix

Add a host line for the smallest address range that covers the client, with a password method, then reload.

# pg_hba.conf
host    appdb    app    198.51.100.7/32    scram-sha-256

sudo -u postgres psql -c "SELECT pg_reload_conf()"

3Verify

Connect from the client.

psql -h 203.0.113.10 -U app -d appdb -c "select 1"

Confirmed by postgresql.org

Did this fix it?

Cause 3 of 3

The server uses another port, or the client uses the wrong host

1Check

port defaults to 5432 and is set per cluster; a second cluster or a custom config changes it.

sudo -u postgres psql -c "SHOW port"
echo "PGHOST=$PGHOST PGPORT=$PGPORT"

2Fix

Use the port the server reports, or fix the stale PGHOST and PGPORT variables.

psql -h 203.0.113.10 -p 5433 -U app -d appdb

3Verify

pg_isready exits with 0 on that port.

pg_isready -h 203.0.113.10 -p 5433

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • List specific addresses in listen_addresses instead of a wildcard when you can.
  • Write pg_hba.conf lines per client address and role, never 0.0.0.0/0 with a weak method.
  • Use pg_isready in monitoring so a stopped listener is noticed early.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.