PostgreSQL: Understanding and Fixing “Peer authentication failed”

This error is common during Linux PostgreSQL setup:

psql -U domain_user -d app_database -W -c "\dt"

FATAL:  Peer authentication failed for user "domain_user"

In most cases, credentials are not the root cause. Authentication method mismatch is.

1) What this error actually means

With peer, PostgreSQL validates OS identity for local socket connections. Password is ignored by design.

OS user running psql is read from kernel context.
PostgreSQL compares it to requested DB user.
Mismatch = immediate failure.

2) Where policy is defined

Usually:

/etc/postgresql/{VERSION}/main/pg_hba.conf

Typical rule:

local   all   all   peer

local means Unix socket (no -h), and peer means OS-based trust.

3) Practical fixes

A) Match OS user

sudo -u domain_user psql -d app_database

B) Force TCP to use `host` rules

psql -h 127.0.0.1 -U domain_user -d app_database -W

C) Production-grade method: `scram-sha-256`

local   all   domain_user   scram-sha-256

Apply and restart:

sudo systemctl restart postgresql

4) Senior checklist

Socket or TCP?
Current OS user?
Correct pg_hba.conf rule present?
Service reloaded/restarted?
Role exists and has privileges?
IPv4/IPv6 rule alignment?

Conclusion

Peer authentication failed is a security feature, not a bug. Once you align connection path and auth policy, access becomes predictable and secure for production workloads.

This post is licensed under CC BY-NC.