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.
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.
First, find your pg_hba.conf file location. You can query PostgreSQL directly if you have sudo access:
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:
local all all peerThis line means: "For all local connections (local), allow all databases (all), for all users (all), use peer authentication."
Peer authentication only works on Unix sockets. If you specify a hostname (including localhost), PostgreSQL uses TCP and will attempt password authentication instead:
# 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_nameFor applications, update your connection string:
postgresql://username:password@localhost:5432/database_name
# instead of
postgresql://username:password@/database_nameThis is often the quickest fix for development and local connections.
Edit pg_hba.conf and change the authentication method. Back up the file first:
sudo cp /etc/postgresql/VERSION/main/pg_hba.conf /etc/postgresql/VERSION/main/pg_hba.conf.backupThen edit the file with sudo:
sudo nano /etc/postgresql/VERSION/main/pg_hba.confFind the line with "peer" (usually at the top):
# 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:
# From:
host all all 127.0.0.1/32 peer
# To:
host all all 127.0.0.1/32 md5Save and exit the editor.
After changing pg_hba.conf, you must reload the configuration. You have two options:
Option 1: Reload (preferred, no downtime)
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/dataOption 2: Restart (if reload doesn't work)
sudo systemctl restart postgresql
# Or on macOS:
# brew services restart postgresqlVerify the configuration took effect:
psql -U username -h localhost -d database_name -c "SELECT version();"If you prefer to keep peer authentication (which is simpler for local development), ensure your system username matches a PostgreSQL user:
# 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
psqlThis works well for development but is less practical for production where services run under different system users.
Test the connection with your chosen method:
# 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_nameIf using peer auth with matching username:
# Should work without password
psql database_nameUser 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.
insufficient columns in unique constraint for partition key
How to fix "insufficient columns in unique constraint for partition key" in PostgreSQL
ERROR 42501: must be owner of table
How to fix "must be owner of table" in PostgreSQL
trigger cannot change partition destination
How to fix "Trigger cannot change partition destination" in PostgreSQL
SSL error: certificate does not match host name
SSL error: certificate does not match host name in PostgreSQL
No SSL connection
No SSL connection to PostgreSQL