Fix: psql: FATAL: Peer authentication failed

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

For connections over the local Unix socket, Debian and Ubuntu’s default pg_hba.conf uses the peer method: PostgreSQL asks the kernel which operating system user is on the other end of the socket and only accepts the connection if that name equals the database role you asked for. You ran psql -U postgres as alice, the names differ, and no password can fix that because peer does not use passwords.

Cause 1: running psql as the wrong OS user

For the postgres superuser, switch to the postgres OS account first. This is the intended way to administer a local server.

sudo -u postgres psql
sudo -u postgres psql -d mydb -c 'SELECT version();'
sudo -i -u postgres      # a shell as postgres, then: psql

Cause 2: an application role without a matching OS user

Your app connects as appuser with a password, which is fine over TCP but not over the socket under peer. The simplest fix is to connect over TCP, where the default rule is password based (scram-sha-256 on current versions).

psql -h localhost -U appuser -d mydb
# or in a connection string
psql 'postgresql://appuser@localhost:5432/mydb'
# DATABASE_URL=postgresql://appuser:secret@localhost:5432/mydb

In an application config, an empty host means the Unix socket; set host=localhost (or 127.0.0.1) explicitly.

Cause 3: you want password login on the socket

Change the method for local connections from peer to scram-sha-256 and reload. Keep the first line for postgres as peer so you can always get in as the OS user.

sudo -u postgres psql -c 'SHOW hba_file;'
sudo nano /etc/postgresql/16/main/pg_hba.conf

# TYPE  DATABASE  USER      ADDRESS  METHOD
# local   all       postgres           peer
# local   all       all                scram-sha-256

sudo systemctl reload postgresql
# or: sudo -u postgres psql -c 'SELECT pg_reload_conf();'

# The role needs a password set
sudo -u postgres psql -c "ALTER ROLE appuser WITH PASSWORD 'change-me';"

Careful: setting the method to trust lets anyone on the machine log in as any role with no password at all. Use it only for a throwaway local development server, never on a shared host. Also check the role was created with a password that uses the current encryption: SHOW password_encryption; should be scram-sha-256, and roles whose password was stored as md5 need it set again after switching.

Cause 4: map OS users to roles instead

If you like peer authentication but your OS user and role names differ, add a user name map. In pg_hba.conf add map=local to the peer line and define the map in pg_ident.conf.

# pg_hba.conf
local   all   all   peer map=local

# pg_ident.conf
# MAPNAME  SYSTEM-USERNAME  PG-USERNAME
local      alice            appuser
local      alice            postgres
local      /^(.*)$          \1

Check that it is fixed

psql -h localhost -U appuser -d mydb -c 'SELECT current_user, inet_server_addr();'
sudo -u postgres psql -c 'SELECT 1'
sudo -u postgres psql -c 'TABLE pg_hba_file_rules;'   # shows the rules as loaded, with any error

When it is not what you think

• password authentication failed is a different method and a wrong password, or a role that has no password set.
• no pg_hba.conf entry for host means no rule matched at all, typically a TCP connection from an address that is not listed; add a host line for that network, and make sure listen_addresses covers it.
• Ident authentication failed is the TCP cousin of peer on RHEL-family defaults; the fix is the same: switch the host line to scram-sha-256.
• role "alice" does not exist means peer succeeded (names matched) but no such database role exists; create it with CREATE ROLE alice LOGIN as postgres.
• If the error appears in a Docker container, the official image’s pg_hba.conf uses trust locally and scram-sha-256 for the network; peer errors there usually come from the host’s own PostgreSQL, not the container.

Official documentation

• PostgreSQL: Peer Authentication
• PostgreSQL: The pg_hba.conf File
• PostgreSQL: User Name Maps