Debugging a missing PostgreSQL connection on macOS

If you have an Apple laptop that you do development on, or otherwise need to run a local app on, you might see this error sometimes:

could not connect to server: No such file or directory. Is the server running locally and accepting connections on Unix domain socket '/tmp/.s.PGSQL.5432'?

This indicates that PostgreSQL is no longer running. If it was previously working fine, we can fix that. Let’s dig in.

You’re going to need the Terminal app.

First up, using pgrep(1) to determine whether Postgres is running:

% pgrep -l postgres

If that gives you no output, that means Postgres isn’t running. Great, we can work with that.

If that does give you output, this blog post isn’t for you. You have another issue than the one we’re solving here, and you might have better luck on Stack Overflow.

Let’s try starting it using brew services, and then we’ll check to see if it’s running:

% brew services start postgresql
% pgrep -l postgres

Still not running? Check the logs with tail(1):

% tail /usr/local/var/log/postgres.log

You may see an error about a file named

FATAL:  lock file "" already exists

This indicates that Postgres had not been shut down cleanly, for any number of reasons. The first line of the file is the process identifier of what once was Postgres. Let’s see what that is now, using a shell command substitution and ps(1):

% ps ax | grep $(head -1 /usr/local/var/postgres/

If you see something about Postgres in the output, then your issue is something deeper and you’ll need to debug more thoroughly before proceeding. But if your output is empty, or you see something unrelated to Postgres, your PID file was stale and we can remove it.

Remove the stale PID lock then start the server again:

% rm /usr/local/var/postgres/
% brew services start postgresql
% pgrep -l postgres

Postgres should now be running.