How to fix FATAL: Peer authentication failed for user in PostgreSQL

PostgreSQLINTERMEDIATEHIGHUpdated Dec 28, 2025· 344 views

Peer authentication failed occurs when PostgreSQL tries to authenticate a connection using peer authentication (Unix socket) but the system username does not match the database username. Change the authentication method in pg_hba.conf or connect via TCP with a password.

Quick fix

Fixes FATAL: Peer authentication failed for user

sudo -u postgres psql -c "SHOW hba_file;"
  1. Check current authentication method in pg_hba.conf
  2. Connect via TCP socket instead of Unix socket
  3. Change authentication method to md5 or password
  4. Reload or restart PostgreSQL
postgresql — error
sudo -u postgres psql -c "SHOW hba_file;"
FATAL: Peer authentication failed for user

What this error means

The "FATAL: Peer authentication failed for user" error occurs when PostgreSQL attempts to authenticate a connection using peer authentication but fails. Peer authentication is a local-only authentication method that validates connections based on the operating system user trying to connect to the database. PostgreSQL expects the system username (the Unix/Linux user) to match the database username. For example, if you are logged in as user "john" but trying to connect to a PostgreSQL user "postgres" or a different database user, peer authentication will reject the connection because the identities do not match. This is a common issue when applications run under a different system user than the PostgreSQL database user (typically "postgres"), or when connecting from a user account that doesn't have a matching PostgreSQL user account.

Typical symptoms

  • Cannot connect to PostgreSQL without using sudo or switching to the postgres system user
  • Error appears when running psql or connecting from applications
  • Connection works fine for the postgres system user but fails for other users
  • Development environment works but production deployment fails due to different system users
  • CI/CD pipeline fails at database connection step

Common causes

  1. System username does not match PostgreSQL username and pg_hba.conf uses peer authentication
  2. Connecting via Unix socket (default) when pg_hba.conf requires peer authentication
  3. Running an application or service as root or a non-postgres user while PostgreSQL is configured for peer auth
  4. PostgreSQL installation has peer authentication for all local connections without alternatives
  5. Mismatched system and database users in containerized or virtualized environments

How to fix "FATAL: Peer authentication failed for user"

1Check current authentication method in pg_hba.conf

First, find your pg_hba.conf file location. You can query PostgreSQL directly if you have sudo access:

bash
sudo -u postgres psql -c "SHOW hba_file;"

Common locations:
- Debian/Ubuntu: /etc/postgresql/VERSION/main/pg_hba.conf
- RHEL/CentOS: /var/lib/pgsql/VERSION/data/pg_hba.conf
- macOS (Homebrew): /usr/local/var/postgres/pg_hba.conf

Then examine the relevant line in pg_hba.conf. It might look like:

bash
local   all   all   peer

This line means: "For all local connections (local), allow all databases (all), for all users (all), use peer authentication."

2Connect via TCP socket instead of Unix socket

Peer authentication only works on Unix sockets. If you specify a hostname (including localhost), PostgreSQL uses TCP and will attempt password authentication instead:

bash
# This uses Unix socket and triggers peer authentication (fails)
psql -U username -d database_name

# This uses TCP/IP and allows password authentication (works)
psql -U username -h localhost -d database_name

# Or specify the host explicitly
psql -U username -h 127.0.0.1 -d database_name

For applications, update your connection string:

bash
postgresql://username:password@localhost:5432/database_name
# instead of
postgresql://username:password@/database_name

This is often the quickest fix for development and local connections.

3Change authentication method to md5 or password

Edit pg_hba.conf and change the authentication method. Back up the file first:

bash
sudo cp /etc/postgresql/VERSION/main/pg_hba.conf /etc/postgresql/VERSION/main/pg_hba.conf.backup

Then edit the file with sudo:

bash
sudo nano /etc/postgresql/VERSION/main/pg_hba.conf

Find the line with "peer" (usually at the top):

bash
# Old (peer auth)
local   all   all   peer

# Change to one of these:
local   all   all   md5        # Password authentication with MD5 hashing
local   all   all   password   # Plain text password (less secure)
local   all   all   scram-sha-256  # Modern password hashing (PostgreSQL 10+)

For remote TCP connections, modify the IPv4 section:

bash
# From:
host    all   all   127.0.0.1/32   peer

# To:
host    all   all   127.0.0.1/32   md5

Save and exit the editor.

4Reload or restart PostgreSQL

After changing pg_hba.conf, you must reload the configuration. You have two options:

Option 1: Reload (preferred, no downtime)

bash
sudo systemctl reload postgresql
# Or on macOS:
# brew services reload postgresql

# Or use pg_ctl reload (requires postgres user):
sudo -u postgres pg_ctl reload -D /var/lib/pgsql/VERSION/data

Option 2: Restart (if reload doesn't work)

bash
sudo systemctl restart postgresql
# Or on macOS:
# brew services restart postgresql

Verify the configuration took effect:

bash
psql -U username -h localhost -d database_name -c "SELECT version();"
5Use the matching system username (alternative)

If you prefer to keep peer authentication (which is simpler for local development), ensure your system username matches a PostgreSQL user:

bash
# Create a PostgreSQL user matching your system username
sudo -u postgres createuser $(whoami)

# Give it permissions if needed
sudo -u postgres psql -c "ALTER USER $(whoami) CREATEDB;"

# Now connect without password using peer auth
psql

This works well for development but is less practical for production where services run under different system users.

6Verify connection works

Test the connection with your chosen method:

bash
# If you changed auth method to md5/password, use TCP:
psql -U username -h localhost -d database_name -W
# -W prompts for password

# Or test with environment variable:
PGPASSWORD="your_password" psql -U username -h localhost -d database_name

# For applications, test the connection string:
psql postgresql://username:password@localhost:5432/database_name

If using peer auth with matching username:

bash
# Should work without password
psql database_name

Advanced notes

User Name Mapping: For more complex setups, PostgreSQL supports user name mapping via pg_ident.conf. This allows you to map system users to different database users without changing authentication globally. See the "map_name" parameter in pg_hba.conf.

Containerization: In Docker, services often run as root or non-postgres users. Change the authentication method to md5/password for container environments, and pass database credentials via environment variables.

Development vs Production: For local development, using the postgres user with peer auth or TCP connections is fine. For production, always use strong authentication (scram-sha-256 or md5) and restrict connections via pg_hba.conf rules based on client IP/hostname.

Socket Location: On some systems, the PostgreSQL socket might not be in the standard location (/tmp on Linux, /var/run/postgresql). You can specify the socket directory explicitly: psql -h /path/to/socket

SELinux/AppArmor: On systems with mandatory access controls, ensure AppArmor or SELinux policies allow your application user to connect to the PostgreSQL socket. Check system logs for denial messages.

Frequently asked questions

What does "FATAL: Peer authentication failed for user" mean?
The "FATAL: Peer authentication failed for user" error occurs when PostgreSQL attempts to authenticate a connection using peer authentication but fails. Peer authentication is a local-only authentication method that validates connections based on the operating system user trying to connect to the database. PostgreSQL expects the system username (the Unix/Linux user) to match the database username.
How do I fix "FATAL: Peer authentication failed for user"?
Peer authentication failed occurs when PostgreSQL tries to authenticate a connection using peer authentication (Unix socket) but the system username does not match the database username. Change the authentication method in pg_hba.conf or connect via TCP with a password.
What causes "FATAL: Peer authentication failed for user"?
System username does not match PostgreSQL username and pg_hba.conf uses peer authentication Connecting via Unix socket (default) when pg_hba.conf requires peer authentication Running an application or service as root or a non-postgres user while PostgreSQL is configured for peer auth
Is the "FATAL: Peer authentication failed for user" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading