PostgreSQL Invalid Password / Password Authentication Failed

A FATAL authentication error indicating the provided password for the specified database user is incorrect, does not match the stored hash, or the user does not exist.

Common Causes

Incorrect password typed during connection.
Password for the user was changed in PostgreSQL but the client is using an old password.
The user account does not exist in the PostgreSQL instance you are connecting to.
The `pg_hba.conf` file is configured for a different authentication method (e.g., `md5` vs. `scram-sha-256`).
Connecting to the wrong PostgreSQL host, port, or database cluster.

How to Fix

1 Verify and Reset User Password

Connect as a superuser (like `postgres`) and reset the password for the target user.

BASH

$ sudo -u postgres psql -c "ALTER USER your_username WITH PASSWORD 'new_secure_password';"

2 Check User Existence and Connection Details

List all users and verify your connection string (host, port, username, database).

BASH

 $ sudo -u postgres psql -c "\du"
# Verify your connection command:
# psql -h localhost -p 5432 -U your_username -d your_database

3 Inspect and Update pg_hba.conf

Check the host-based authentication file for the correct method and restart PostgreSQL.

BASH

 $ sudo cat /etc/postgresql/*/main/pg_hba.conf
# Look for the relevant line for your connection.
# Common fix: Change 'peer' or 'ident' to 'md5' or 'scram-sha-256' for host connections.
sudo systemctl restart postgresql

4 Test Connection with Password File (~/.pgpass)

Use a .pgpass file to avoid typing errors and ensure the correct password is used.

BASH

 $ echo "localhost:5432:*:your_username:your_password" > ~/.pgpass
chmod 600 ~/.pgpass
# Then attempt connection:
psql -h localhost -U your_username