connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory

What it means

When you run psql (or any libpq program) without -h and without PGHOST, it doesn’t use the network. It connects through a Unix-domain socket: a special file named .s.PGSQL.<port> in a socket folder, which the server creates when it starts. The client looked for that file and it wasn’t there:

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory
	Is the server running locally and accepting connections on that socket?

The path in the message is where it looked. The folder is built into the client: /tmp for Homebrew and most Mac builds, /var/run/postgresql for Debian and Ubuntu packages and the official Docker image. The number is the port, 5432 unless you set another.

Clients built with libpq 13 or older word the same failure as could not connect to server: No such file or directory, followed by a question ending in Unix domain socket "/tmp/.s.PGSQL.5432"? (we had no client that old to check it with).

Common causes

1. No server running on this machine. It never started, it stopped, or it failed to start (a leftover postmaster.pid after a crash, a full disk, a bad setting).
2. The server runs elsewhere: in Docker, in a virtual machine, on another host. Its socket file is inside that system, not on your Mac.
3. A different port. Two PostgreSQL versions installed side by side often use 5432 and 5433; the socket file name includes the port.
4. A different socket folder. A psql from one packaging looks in /tmp, a server from another puts its socket in /var/run/postgresql, or the reverse.

How to fix it

Check whether a server is running, and where

ls -la /tmp/.s.PGSQL.* /var/run/postgresql/.s.PGSQL.* 2>/dev/null
pg_isready

On a Mac with Homebrew, brew services list shows whether its PostgreSQL service is running; Postgres.app shows its servers in its window. If a server is running and you can connect some other way, SHOW unix_socket_directories; and SHOW port; tell you where its socket is.

Start the server

Homebrew: brew services start postgresql@18 (use your version). Postgres.app: start it from the app. If it won’t start, its log says why, for example lock file "postmaster.pid" already exists when that file was left behind by a crash and its process number now belongs to another program.

Point the client at the right socket or port

psql -h /var/run/postgresql -p 5432 -U <user> <database>   # a socket folder: -h takes a path
psql -p 5433 -U <user> <database>                          # another port

A host that starts with / is a socket folder. You can also set PGHOST and PGPORT.

Use TCP instead

For a server in Docker, a virtual machine or another machine, connect over the network:

psql -h localhost -p 5432 -U <user> <database>

With Docker, the port must be published (-p 5432:5432). If that fails with “Connection refused”, see Connection refused. Once you reach the server, the next message may be about the password: see no password supplied.

Reproduce it

On a Mac, with psql 18.6 and no server on port 5433:

psql -U postgres -d postgres -p 5433

psql: error: connection to server on socket "/tmp/.s.PGSQL.5433" failed: No such file or directory
	Is the server running locally and accepting connections on that socket?

psql -h /var/run/postgresql on the Mac, where that folder doesn’t exist, gave the same message for /var/run/postgresql/.s.PGSQL.5432. Inside a throwaway postgres:18 container with the server not started, plain psql -U postgres looked in /var/run/postgresql and failed the same way. When we then left a socket file there with nothing listening on it (as a crashed server can), the error became:

psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: Connection refused
	Is the server running locally and accepting connections on that socket?

In Inlet

In Inlet, a connection names its host and port; paste a connection URL and Inlet fills the form. TLS and SSH tunnels (Pro) are there when the server is remote, and Inlet can import connections from ~/.pgpass, pg_service.conf and a .env DATABASE_URL. When a connection fails, Inlet shows the error, and What this error means opens its page here.