psql "connection to server on socket ... failed: No such file or directory": How to Fix It
psql connection to server on socket failed means no Postgres socket file was where psql looked. Fixes for a stopped server, wrong path, Docker and Homebrew.
This error means psql tried to reach Postgres through a local socket file and the file wasn't there. Usually the server isn't running. Less often it is running, but its socket lives in a different directory, uses a different port number, or sits inside a Docker container where psql on your machine can't see it. Start the server, or tell psql where the server actually is with -h and -p.
Checked against the PostgreSQL 18 documentation, the libpq source, Debian's packaging patches and the Homebrew formula in November 2026.
On Debian, Ubuntu and most Linux servers the error looks like this:
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: No such file or directory
Is the server running locally and accepting connections on that socket?
On macOS with Homebrew (or any build that uses the upstream default) the path is /tmp:
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?
psql 13 and older word it differently ("could not connect to server: No such file or directory ... connections on Unix domain socket"), but the meaning and the fixes are the same.
What psql is looking for
When you run psql with no host, it doesn't use the network. The psql docs say: "If you omit the host name, psql will connect via a Unix-domain socket to a server on the local host." A Unix-domain socket is a special file that the server creates when it starts.
The file name comes from the port. According to the server configuration docs, the socket is named .s.PGSQL.nnnn "where nnnn is the server's port number", so the default port 5432 gives .s.PGSQL.5432. The directory is set by unix_socket_directories, whose default "is normally /tmp, but that can be changed at build time." Debian and Ubuntu packages change it to /var/run/postgresql.
So the error message tells you exactly what psql expected: a directory and a port. If the server is stopped, or uses another directory or port, the file isn't there.
| What psql expected | What's actually true | Fix |
|---|---|---|
| Server running | Server stopped or crashed | Start it, read the log if it won't start |
/var/run/postgresql |
Server's socket is in /tmp (or vice versa) |
psql -h /tmp (the directory) |
| Port 5432 | Server runs on 5433 | psql -p 5433 |
| A local server | Postgres runs in Docker | psql -h localhost (TCP) |
Step 1: is the server running?
This is the cause most of the time, especially after a reboot or an upgrade.
Debian and Ubuntu:
pg_lsclusters
This lists every installed cluster with its version, port and status. If yours says down, start it:
sudo systemctl start postgresql
# or start one specific cluster:
sudo pg_ctlcluster 16 main start
If it goes straight back to down, the reason is in the log file shown in the last column of pg_lsclusters (typically /var/log/postgresql/postgresql-16-main.log). Common reasons are a full disk, a typo in postgresql.conf, or another process already using the port.
macOS with Homebrew:
brew services list
brew services start postgresql@17
Use the formula you actually installed (postgresql@16, postgresql@18 and so on). Homebrew writes the server log to $(brew --prefix)/var/log/postgresql@17.log. After a crash or a forced shutdown you may see FATAL: lock file "postmaster.pid" already exists there. Only delete that file from the data directory ($(brew --prefix)/var/postgresql@17) after you have confirmed no postgres process is running (pgrep -l postgres), since removing it under a live server can corrupt data.
Other Linux distributions usually run Postgres as a systemd service called postgresql or postgresql-<version>: systemctl status postgresql is the place to start.
Step 2: the server runs, but somewhere else
If the server is up and you still get the error, psql and the server disagree about the address.
A different socket directory
This happens when psql and the server come from different builds. A common case is a psql installed from one source (for example the Debian postgresql-client package) talking to a server built with the upstream default. Tom Lane, a long-time Postgres core developer, describes it on the mailing list: the server puts its socket in /tmp while psql's libpq looks in /var/run/postgresql.
Find where the socket really is:
ls -la /var/run/postgresql/ /tmp/.s.PGSQL.* 2>/dev/null
Then point psql at that directory. A host value that starts with a slash is treated as a socket directory, per the libpq docs:
psql -h /tmp -U postgres
You can make this permanent with export PGHOST=/tmp in your shell profile, or by setting unix_socket_directories in postgresql.conf to the directory your clients expect and restarting the server. Don't create symlinks to the socket as a fix: they break on every restart. Better still, remove the second Postgres installation if you didn't mean to have two.
A different port
On Debian and Ubuntu, installing a second major version next to the first gives the new cluster the next free port, often 5433. pg_lsclusters shows the port of each. Connect with:
psql -p 5433
The socket name changes with the port (.s.PGSQL.5433), which is why psql reports a missing file instead of "wrong port".
Step 3: Postgres runs in Docker
A container's socket file lives inside the container's filesystem. psql on your host can't see it, so the plain psql command fails with this exact error even though the database is fine.
Connect over TCP instead. This only works if the container publishes the port (-p 5432:5432 or ports: ["5432:5432"] in Compose):
psql -h localhost -p 5432 -U postgres
Or run psql inside the container, where the socket does exist:
docker exec -it <container-name> psql -U postgres
If -h localhost then gives "Connection refused", the port isn't published or the container isn't running. That's a different problem, covered in ECONNREFUSED 127.0.0.1:5432: Why Your App Can't Reach the Database.
The errors you might hit next
Once psql reaches the socket, a few follow-on errors are common.
Permission denied:
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: Permission denied
The socket exists, but your user can't open it or the directory it sits in. By default the socket is open to everyone (unix_socket_permissions defaults to 0777), so check whether someone tightened that setting or unix_socket_group, and look at the directory's permissions with ls -ld /var/run/postgresql.
Role does not exist:
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: role "alice" does not exist
With no -U, psql logs in as a database user with the same name as your operating-system user. A fresh install only has the postgres role. Connect as that and create your own role, as described in Postgres Roles and Permissions: CREATE USER, GRANT, and Least Privilege:
sudo -u postgres psql
Peer authentication failed:
psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: Peer authentication failed for user "postgres"
Debian and Ubuntu configure local socket connections to use peer authentication, which takes your operating-system user name from the kernel and only accepts it as the matching database user. Running psql -U postgres as yourself fails; running it as the postgres system user (sudo -u postgres psql) works. If you want password login, connect over TCP with -h localhost, which goes through the password rules in pg_hba.conf. A wrong password there gives a different error, covered in Postgres "password authentication failed for user": How to Fix It.
Quick checklist
- Read the path in the error: it tells you the directory and port psql expected.
- Check the server is running (
pg_lsclusters,brew services list,systemctl status postgresql). - If it won't start, read the server log before changing anything.
- Find the real socket (
ls /var/run/postgresql /tmp/.s.PGSQL.*) and use-h <directory>and-p <port>. - For Docker, use
-h localhostordocker exec ... psql. - Once connected, use
\conninfoto see how you got in. How to View Your Postgres Database covers GUI options if you'd rather not live in psql.
EasySpawn provisions a managed Postgres automatically on the same server where Claude Code works, so the database is already running when the agent needs it and nobody has to go looking for socket files. It is pre-launch; you can join the waitlist.
Related: ECONNREFUSED 127.0.0.1:5432: Why Your App Can't Reach the Database · How to View Your Postgres Database: psql, GUIs, and VS Code · Postgres Roles and Permissions: CREATE USER, GRANT, and Least Privilege · Postgres Connection Strings Explained: Format, Examples, and Common Errors
Keep reading
MongoDB "E11000 duplicate key error": What It Means and How to Fix It
MongoDB E11000 duplicate key error means a write broke a unique index. How to read it, fix null and stale-index cases, find duplicates and handle code 11000.
What Is UTF-8? Character Encoding and Garbled Text (Mojibake) Explained
UTF-8 is the character encoding that lets computers store every language and emoji as bytes — and it's the default almost everywhere now. How encoding works, why you see garbled text like ’ or é, and how to fix it in HTML, databases, CSV files and code.