Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

brew services says PostgreSQL started, but psql cannot connect

Errorbrew services list shows postgresql@17 as started, yet psql cannot connect

Short answer

brew services start only registers the service with launchd, it does not prove the server is up. Check the status column first. A server that died leaves postmaster.pid behind, and a client may be aimed at a different socket or port than the server uses. Ask pg_isready which of these it is.

  • Applies to macOS 15, Homebrew 4, PostgreSQL 16, PostgreSQL 17
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask PostgreSQL itself whether it accepts connections, and look at the service status. Exit code 0 means yes, 2 means no response.

    brew services list
    pg_isready -h localhost -p 5432
  2. 2Match what you see, then jump to its fix

    1. 1brew services list does not show the service as started, and pg_isready exits with 2.The service is not runningFix
    2. 2The service restarts but stays in error; the data directory contains postmaster.pid although nothing runs.A stale postmaster.pid from a crash or a forced shutdownFix
    3. 3pg_isready works against localhost but psql fails, or the server listens on another port.The client is aimed at another host, port or socket than the serverFix

What does the error look like?

  • brew services list shows postgresql@17 as started, yet psql cannot connect
  • pg_isready exits with status 2 (no response to the connection attempt)

Cause 1 of 3

The service is not running

1Check

Homebrew manages the service with launchctl. start registers it to launch at login, run starts it without registering, and a stopped service has to be started again.

brew services info --all

2Fix

Restart the service, which stops it if needed and starts it again.

brew services restart postgresql@17

3Verify

The status shows started, and pg_isready exits with 0.

pg_isready -h localhost -p 5432; echo $?

Confirmed by docs.brew.sh

Did this fix it?

Cause 2 of 3

A stale postmaster.pid from a crash or a forced shutdown

1Check

postmaster.pid is a lock file that records the postmaster's process ID and data directory, and it is not present after a clean shutdown. A copy left behind after a crash can stop a new start. Be sure no postgres process is alive before touching it.

ps aux | grep '[p]ostgres'
ls <data-directory>/postmaster.pid

2Fix

If no postgres process is alive, remove the stale file and start the service again.

rm <data-directory>/postmaster.pid
brew services start postgresql@17

3Verify

pg_isready exits with 0.

pg_isready -h localhost -p 5432

Confirmed by postgresql.org

Did this fix it?

Cause 3 of 3

The client is aimed at another host, port or socket than the server

1Check

Without a host, psql uses a Unix-domain socket in the default socket directory; with a port in PGPORT or the command line, it uses that port.

echo "$PGHOST $PGPORT"
which psql

2Fix

Use the same host and port as the server, for example over TCP, or unset stray variables.

psql -h localhost -p 5432 postgres

3Verify

psql opens a session.

psql -h localhost -p 5432 postgres -c 'SELECT 1;'

Confirmed by postgresql.org

Did this fix it?

How do I stop it coming back?

  • Keep one PostgreSQL major version installed through Homebrew, or note the port each one uses.
  • Use brew services restart after an upgrade so launchd starts the new version.
  • Do not delete files inside the data directory unless you know what each one does.

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

Databases

Postgres.app on macOS will not start a server on port 5432

Could not delete stale postmaster.pid file

Postgres.app fails to start when something else already holds port 5432, when another server uses the same data directory, or when a crash left a stale postmaster.pid.

4 causes, each with a fix

Next step

Want this handled for good?

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