psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed:
FATAL:  Peer authentication failed for user "myapp"

This is the most common PostgreSQL error on fresh Debian and Ubuntu installs. It doesn’t mean your password is wrong — PostgreSQL didn’t even ask for one. It means the authentication method for local socket connections is peer, and your Linux username doesn’t match the database role you asked for.

How peer authentication works

pg_hba.conf decides how each connection authenticates. Debian/Ubuntu defaults (/etc/postgresql/<version>/main/pg_hba.conf):

# TYPE  DATABASE  USER      ADDRESS        METHOD
local   all       postgres                 peer
local   all       all                      peer
host    all       all       127.0.0.1/32   scram-sha-256
host    all       all       ::1/128        scram-sha-256
  • local — connections over the Unix socket (no -h given).
  • peer — PostgreSQL asks the kernel which Linux user owns the connecting process, and allows the connection only if it equals the requested database role name.
  • host … scram-sha-256 — TCP connections authenticate with a password.

So when Linux user alice runs psql -U myapp, peer authentication fails: alice ≠ myapp.

Fix 1: connect over TCP (most common)

Add -h 127.0.0.1 (or -h localhost) so the host rule with password authentication applies:

psql -h 127.0.0.1 -U myapp -d myapp

This is exactly what applications do when you set the host to 127.0.0.1 or localhost in their database settings. Set the role’s password if it doesn’t have one:

sudo -u postgres psql -c "\password myapp"

Fix 2: run as the matching Linux user

For administration, run psql as the postgres Linux user, which matches the postgres role:

sudo -u postgres psql

Or create a Linux user with the same name as the role (rarely worth it for apps).

Fix 3: map Linux users to roles (pg_ident.conf)

Allow specific Linux users to connect as specific roles via peer:

# pg_ident.conf
# MAPNAME   SYSTEM-USERNAME   PG-USERNAME
appmap      deploy            myapp
# pg_hba.conf (before the generic local line)
local   myapp   myapp   peer map=appmap

Reload: sudo systemctl reload postgresql. Now Linux user deploy can connect as myapp over the socket without a password — handy for cron jobs and scripts.

Fix 4: change the local method to password authentication

If you want password authentication for socket connections too:

local   all   postgres                 peer
local   all   all                      scram-sha-256

Keep peer for postgres so sudo -u postgres psql keeps working. Reload PostgreSQL afterwards. Order matters: the first matching line wins.

Never use trust (no authentication at all) outside throwaway test machines.

FATAL: password authentication failed for user "myapp" — now you’re on a password method; the password is wrong, or the role has no password, or it was stored as MD5 while scram-sha-256 is required — reset it with \password.

FATAL: no pg_hba.conf entry for host "…", user "…", database "…" — no line matches the connection; add one (see PostgreSQL remote connections).

FATAL: role "alice" does not exist — psql defaults to your Linux username as the role; pass -U explicitly.

FATAL: database "alice" does not exist — psql defaults the database name to the role name; pass -d.

Checking which rule applies

SELECT line_number, type, database, user_name, address, auth_method
FROM pg_hba_file_rules;

This view (PostgreSQL 10+) shows the parsed rules and flags errors in the file.

Related: PostgreSQL users and databases and psql commands.

  • PostgreSQL
  • Authentication
  • Troubleshooting