DEV Community

Cover image for Fix: Peer Authentication Failed for User "postgres"
Mahdi BEN RHOUMA
Mahdi BEN RHOUMA

Posted on Originally published at iloveblogs.blog

Fix: Peer Authentication Failed for User "postgres"

#postgres #pghbaconf #peerauthentication #supabaselocal

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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;'
Enter fullscreen mode Exit fullscreen mode

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

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     peer
Enter fullscreen mode Exit fullscreen mode

Change peer to scram-sha-256:

local   all             all                                     scram-sha-256
Enter fullscreen mode Exit fullscreen mode


Setting the method to trust makes the error go away by disabling auth entirely — any local user can connect as any role, including the superuser. Fine on an isolated throwaway VM, dangerous on any shared or developer machine. Use scram-sha-256 and a real password.

Step 2 — Reload PostgreSQL 

sudo systemctl reload postgresql
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
ALTER USER postgres PASSWORD 'a-strong-dev-password';
Enter fullscreen mode Exit fullscreen mode

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

Originally published at https://www.iloveblogs.blog

Top comments (0)