PostgreSQL: understanding and resolving the "peer authentication failed" error

During the configuration of PostgreSQL on Linux systems, this specific error frequently appears in both production and staging environments:

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

Resulting Output:

FATAL:  Peer authentication failed for user "domain_user"

In the vast majority of cases, the password is correct and the user exists, yet the connection is decisively rejected. The problem is almost always an authentication policy applied to the wrong connection type, rather than an invalid credential.

2) The source of truth: pg_hba.conf#

On Linux systems, the host-based authentication (HBA) file is typicaly located at:

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

A common line responsible for this behavior looks like this:

# TYPE  DATABASE        USER            METHOD
local   all             all             peer

Operational Breakdown:

• local: Refers to connections made via the Unix-domain socket (connections without -h).
• all: Applies to all databases and all users.
• peer: Validates based on OS identity, bypassing traditional password checks.

4) Remediation strategies (pros and cons)#

Option 1: Execute as the matching OS user#

If the environment relies on controlled local execution, the most direct fix is to align the OS user with the database role:

sudo -u domain_user psql -d app_database

• Best For: Internal cron jobs, local automation, or root-to-service-account transitions.

Option 2: Force TCP connection (the troubleshooting bypass)#

To quickly bypass local rules and validate if your password is correct via host rules:

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

This forces the evaluation of host rules in pg_hba.conf, which usually allow password-based entry.

Option 3: Migrate to scram-sha-256 (recommended for production)#

For full-stack applications and services that strictly require strong password authentication locally, the definitive fix is to update the method in pg_hba.conf.

1. Edit the Configuration:

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

1. Apply the Rule:

local   all   domain_user   scram-sha-256

1. Restart or Reload Service:

sudo systemctl restart postgresql

Security Warning: Avoid using the legacy md5 method in new environments. SCRAM-SHA-256 is the modern standard, offering significantly more resistance against capture/replay attacks.

6) Technical method comparison#

See also

Development From module errors to bun-only: the real prisma troubleshooting guide on Linux

Development PostgreSQL startup failed: `could not create lock file "/var/run/postgresql/.s.pgsql.5432.lock"

Development Migrating tools to Python 3.13 on Kali Linux: from TLS handshakes to c-api changes

This post is licensed under CC BY-NC.