psql: FATAL: password authentication failed for user

The error “psql: FATAL: password authentication failed for user” means PostgreSQL rejected your login attempt because the password provided did not match the stored credentials for that user.

What It Means

PostgreSQL stores password hashes in pg_authid. When you connect, the server compares your supplied password against the stored hash using the authentication method configured in pg_hba.conf (usually md5 or scram-sha-256). If they do not match, the connection is refused.

Why It Happens

• The password was typed incorrectly or has changed.
• The user does not exist in the PostgreSQL cluster.
• The pg_hba.conf entry for your connection uses peer or trust but you supplied a password anyway.
• The connection is routed to the wrong database or wrong host.
• The password contains special characters that were not properly escaped in the command line.
• The user’s password was expired or the account was locked.

How to Fix It

1. Reset the user’s password

sudo -u postgres psql
ALTER USER youruser WITH PASSWORD 'NewStrongPassword';

2. Verify the user exists

sudo -u postgres psql
\du

3. Check pg_hba.conf authentication method

sudo grep -v '^#' /etc/postgresql/*/main/pg_hba.conf

Ensure the line for your connection uses md5 or scram-sha-256, not peer or trust.

4. Reload the configuration after changes

sudo systemctl reload postgresql

5. Connect with explicit parameters

psql -h localhost -U youruser -d yourdb -W

FAQ