Fix: Peer Authentication Failed for User "postgres"

You fire up local PostgreSQL, type psql -U postgres, and the connection dies with:

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

The Stack Overflow thread with ~1.3M views (Q18664074) has the diagnosis: peer authentication compares the OS username to the database role, and they don't match. You ran psql as your own OS user (e.g. mahdi) but asked to connect as role postgres. Peer auth says no.

This is a local-dev issue, not a production one — peer auth is only the default for local connections in pg_hba.conf. Here are the two correct fixes.

Fix 1 — Connect as the matching OS user#

The cleanest fix: become the user PostgreSQL expects.

sudo -u postgres psql

postgres is both the OS account the server runs as and the default superuser role. Peer auth now sees OS user postgres connecting as role postgres — match, allowed.

If you need your own database role, create it and connect as yourself:

sudo -u postgres createuser --superuser $USER
sudo -u postgres createdb $USER
psql   # now peer auth matches: OS user mahdi -> role mahdi

Fix 2 — Switch the local method to scram-sha-256#

If you want to connect as role postgres from your own OS user with a password (common for app dev), change the auth method.

Step 1 — Edit pg_hba.conf#

Find it with:

sudo -u postgres psql -c 'SHOW hba_file;'

Open the file and find the local line near the top:

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     peer

Change peer to scram-sha-256:

local   all             all                                     scram-sha-256

Step 2 — Reload PostgreSQL#

sudo systemctl reload postgresql

Reload is enough — pg_hba.conf changes do not need a full restart.

Step 3 — Set a password for the role#

Peer auth never used one, so the role likely has none. Connect as the postgres OS user first, then set it:

sudo -u postgres psql

ALTER USER postgres PASSWORD 'a-strong-dev-password';

Now psql -U postgres -h localhost will prompt for that password and succeed.

Supabase local dev#

Supabase's local stack (the supabase CLI with supabase start) runs Postgres in a container with its own auth setup — peer auth is not the issue there. The usual gotchas:

• The postgres role has a fixed password set by POSTGRES_PASSWORD in .env — connect with postgresql://postgres:postgres@localhost:54322/postgres (port 54322, not 5432).
• Studio runs on 54323. Use the DB port, not the studio port, in your connection string.
• If you changed the password, recreate the volume: supabase stop && supabase start — the password is baked into the initialized data directory.

For the related local-dev auth pitfalls when wiring Supabase into Next.js, see common Next.js + Supabase mistakes.

Why peer auth exists#

Peer auth lets PostgreSQL delegate authentication to the OS: if you are already logged in as user mahdi on a secure multi-user box, that is proof enough — no password to leak. It is secure and zero-config when the OS user and PG role match by convention. The error is the system correctly refusing a mismatch, not a bug.

Common mistakes#

• trust to make it stop — disables auth; use scram-sha-256 instead.
• Editing the wrong pg_hba.conf — there can be several (Debian vs Homebrew vs Docker). Confirm with SHOW hba_file; before editing.
• Forgetting to reload — pg_hba.conf is re-read on reload, not on every connection; run systemctl reload postgresql.
• Not setting a password — after switching to scram-sha-256, the role still needs a password or every login fails differently (password authentication failed).
• Port confusion in Supabase local — DB is 54322, not 5432.

Official references: PostgreSQL — Client Authentication (pg_hba.conf), Auth Methods — Peer Authentication.

Related Articles#

• Next.js + Supabase Common Mistakes
• Supabase Slow Queries Fix
• Debugging Supabase RLS Issues
• Supabase Foreign Key Constraint Violation Fix
• PostgreSQL: Could Not Serialize Access — Concurrent Update Fix
• Fix: password authentication failed for user "postgres"