Peer authentication failed for user, on a local PostgreSQL connection
FATAL: Peer authentication failed for user "postgres"Short answer
A pg_hba.conf line with method peer only lets a local socket client in when its OS user name equals the requested database user. Either run as that OS user (sudo -u postgres psql), connect over TCP with a password, or add a user name map.
Fix it fast
1Find out which cause you have
Find the pg_hba.conf the server is really using and read the local lines. The first line that matches your connection is the only one applied.
sudo -u postgres psql -c "SHOW hba_file" sudo -u postgres psql -c "SELECT line_number, type, database, user_name, address, auth_method FROM pg_hba_file_rules"2Match what you see, then jump to its fix
- 1
You ran psql -U postgres (or an app did) from an account that is not postgres, and the matching line says peerYour OS user is not the database user you asked forFix - 2
The app has no host set, so it uses the Unix socket and hits the local peer lineAn application connects through the local socket, where peer is the ruleFix - 3
You want one OS account (say a deploy user) to act as one database role without a passwordThe OS user must log in as a different database roleFix
- 1
What does the error look like?
FATAL: Peer authentication failed for user "postgres"psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: Peer authentication failed for user "postgres"
Cause 1 of 3
Your OS user is not the database user you asked for
1Check
Peer authentication reads your OS user name from the kernel and compares it with the database user. They must be equal.
whoami
sudo -u postgres psql -c "SELECT current_user"2Fix
Run the client as the OS user that matches, or choose a database user that matches your OS user.
sudo -u postgres psql
# or: a role named like your own OS user
psql -U "$(whoami)" -d postgres3Verify
The prompt opens without a password question.
sudo -u postgres psql -c "\conninfo"Confirmed by postgresql.org
Cause 2 of 3
An application connects through the local socket, where peer is the rule
1Check
Without a host, libpq and psql use the Unix-domain socket, which is matched by local lines. TCP connections match host lines instead.
grep -vE '^\s*(#|$)' "$(sudo -u postgres psql -Atc 'SHOW hba_file')"2Fix
Give the application a host and a password for its own role, and make sure a host line allows that role. Then it never touches the peer line.
# pg_hba.conf
host appdb appuser 127.0.0.1/32 scram-sha-256
# connection string
postgresql://appuser:SECRET@127.0.0.1:5432/appdb3Verify
Reload the server and test as the app user over TCP.
sudo -u postgres psql -c "SELECT pg_reload_conf()"
psql "host=127.0.0.1 dbname=appdb user=appuser" -c "select 1"Confirmed by postgresql.org
Cause 3 of 3
The OS user must log in as a different database role
1Check
peer accepts a map= option that translates OS names to database names through pg_ident.conf.
sudo -u postgres psql -c "SHOW ident_file"2Fix
Add a map and point the local line at it.
# pg_ident.conf MAPNAME OS-USER DB-USER
deploymap deploy appuser
# pg_hba.conf
local appdb appuser peer map=deploymap3Verify
Reload and connect as the OS user.
sudo -u postgres psql -c "SELECT pg_reload_conf()"
sudo -u deploy psql -U appuser -d appdb -c "select current_user"Confirmed by postgresql.org
How do I stop it coming back?
- Keep peer for admin access on the server and use scram-sha-256 over TCP for applications.
- Check pg_hba_file_rules after every edit; rows with an error value point at the broken line.
- Remember that changes need a reload, not a restart.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Databases
Ident authentication failed for user when connecting over TCP
psql: error: connection to server at "127.0.0.1", port 5432 failed: FATAL: Ident authentication failed for user "postgres"
A host line in pg_hba.conf uses method ident, so the server asked the client machine's ident service which OS user opened the connection, and the answer did not match the database user.
3 causes, each with a fixDatabases
psql says the role does not exist, even for postgres or your own user
FATAL: role "username" does not exist
The server found no role with the name the client sent.
3 causes, each with a fixDatabases
DBeaver cannot run pg_restore: the utility is not found in the client home
Utility 'pg_restore' not found in client home '/usr/lib' (/usr/lib)
DBeaver runs pg_restore from a local PostgreSQL client folder; it does not bundle one.
3 causes, each with a fixDatabases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
manage.py test stops with 'permission denied to create database' on PostgreSQL
django.db.utils.ProgrammingError: permission denied to create database
Django creates a separate database called test_ plus your database name, using the DATABASES USER.
2 causes, each with a fixDatabases
An EC2 instance cannot reach its RDS database
Could not open connection to the host, on port <port>: Connect failed
RDS denies all access until a security group allows it.
3 causes, each with a fix