Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Peer authentication failed for user, on a local PostgreSQL connection

ErrorFATAL: 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.

  • Applies to PostgreSQL 16, PostgreSQL 17, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1You 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. 2The 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. 3You 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

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 postgres

3Verify

The prompt opens without a password question.

sudo -u postgres psql -c "\conninfo"

Confirmed by postgresql.org

Did this fix it?

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/appdb

3Verify

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

Did this fix it?

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=deploymap

3Verify

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

Did this fix it?

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.