Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

pgAdmin cannot connect to the PostgreSQL server: timeout expired

ErrorTimeout expired

Short answer

Timeout expired means pgAdmin sent a connection request and heard nothing back within its limit. Test the host and port with pg_isready first. If it gets no response, the server is not listening on that address or something blocks the path. If it answers, raise the connection timeout or use an SSH tunnel.

  • Applies to pgAdmin 4 9.x, PostgreSQL 16, PostgreSQL 17
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    From the machine that runs pgAdmin, ask the server whether it answers on that host and port. Exit code 2 means no response.

    pg_isready -h db.example.com -p 5432 -t 5
    echo $?
  2. 2Match what you see, then jump to its fix

    1. 1pg_isready returns 2 from another machine but 0 on the server itselfThe server listens only on localhostFix
    2. 2pg_isready works with the right address but pgAdmin uses another oneThe host or port in the pgAdmin server entry is wrongFix
    3. 3pg_isready returns 2 from your laptop, but works from a jump hostThe database is on a private networkFix
    4. 4pg_isready returns 0 but pgAdmin still times outThe server is slow to answer and pgAdmin gives up at 10 secondsFix

What does the error look like?

  • Timeout expired

Cause 1 of 4

The server listens only on localhost

1Check

The default listen_addresses is localhost, which allows only local loopback connections. A remote pgAdmin never gets an answer.

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

2Fix

Set listen_addresses to the interface you need (or '*' for all) in postgresql.conf and restart. The setting is read at server start only.

# postgresql.conf
listen_addresses = '*'
# then restart
sudo systemctl restart postgresql

3Verify

pg_isready now returns 0 from the pgAdmin machine.

pg_isready -h db.example.com -p 5432

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 4

The host or port in the pgAdmin server entry is wrong

1Check

Open the server's Properties, then the Connection tab, and compare host name and port with what pg_isready accepted. The default port is 5432.

pg_isready -h <host from pgAdmin> -p <port from pgAdmin>

2Fix

Correct the Host name/address and Port on the Connection tab and save.

# pgAdmin: right-click server > Properties > Connection
# Host name/address: db.example.com
# Port: 5432

3Verify

Connect again and the server tree opens.

pg_isready -h db.example.com -p 5432

Confirmed by pgadmin.org

Did this fix it?

Cause 3 of 4

The database is on a private network

1Check

If the server is reachable only from inside a network, pgAdmin cannot reach it directly.

pg_isready -h 10.0.0.5 -p 5432 -t 5

2Fix

Use the SSH Tunnel tab: enable Use SSH tunneling and enter the tunnel host, port and user. Set the Connection host to the address the SSH host sees.

# pgAdmin > Properties > SSH Tunnel
# Use SSH tunneling: Yes
# Tunnel host / Tunnel port / Username

3Verify

Connect and the timeout error is gone.

pg_isready -h db.example.com -p 5432

Confirmed by pgadmin.org

Did this fix it?

Cause 4 of 4

The server is slow to answer and pgAdmin gives up at 10 seconds

1Check

pgAdmin's connection timeout is 10 seconds by default. A server that is starting or far away can exceed it.

pg_isready -h db.example.com -p 5432 -t 30

2Fix

On the Parameters tab raise the Connection timeout. The docs advise against anything under 2 seconds.

# pgAdmin > Properties > Parameters
# Connection timeout: 30

3Verify

Reconnect and watch the server tree load.

pg_isready -h db.example.com -p 5432

Confirmed by pgadmin.org

Did this fix it?

How do I stop it coming back?

  • Keep one saved pgAdmin entry per server and check host and port after any server move.
  • Run pg_isready in monitoring so a down server is found before pgAdmin shows a timeout.
  • Reach private databases through SSH tunnels, not by opening the port to everyone.

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.