Fix: FATAL: password authentication failed for user

The error looks like this (note the two spaces after FATAL:, as PostgreSQL prints it):

FATAL:  password authentication failed for user "appuser"

It means the connection got all the way to the server, a line in pg_hba.conf matched and asked for a password (scram-sha-256, md5 or password), and the password check did not pass. Because the first matching rule is final, PostgreSQL does not try any other rule.

Look at the server log first

For security the client gets a short message, but the server log usually says more, including which pg_hba.conf line was used. On Debian and Ubuntu the log is under /var/log/postgresql/; elsewhere check log_directory in the data directory or journalctl -u postgresql.

sudo tail -n 50 /var/log/postgresql/postgresql-18-main.log
sudo journalctl -u postgresql --since '10 minutes ago'

Causes, most likely first

1. Wrong password, or the password in the application’s config, environment or ~/.pgpass differs from the one you think. Watch for trailing spaces and characters that need escaping in connection URLs (@, :, /, % must be percent-encoded).
2. The role has no password. A role created with CREATE ROLE ... LOGIN and no PASSWORD can never pass password authentication. The default postgres superuser on Debian and Ubuntu has no password; it is meant for peer authentication over the local socket.
3. Wrong user name. Many clients default to your operating system user name when you do not give one. Check what the error message shows in quotes.
4. The password has expired. A role with VALID UNTIL in the past fails password authentication.
5. Password stored in an incompatible format. If pg_hba.conf says scram-sha-256 but the role’s password was stored as an MD5 hash (common after upgrades from old versions), SCRAM authentication cannot use it. Set the password again.
6. You are connecting to a different server than you think, for example a container or a second local install listening on the same port, where the role has a different password.

Fix it step by step

1. Connect as a superuser through a path that does not need the password, usually the local socket with peer authentication: sudo -u postgres psql.
2. Check that the role exists, can log in and has no expired password.
3. Set a new password with \password, which sends it hashed instead of in a plain SQL statement.
4. Test from the client with the exact same host, port, user and database the application uses.

SELECT rolname, rolcanlogin, rolvaliduntil FROM pg_roles WHERE rolname = 'appuser';
\password appuser
ALTER ROLE appuser VALID UNTIL 'infinity';

psql "host=db1.example.com port=5432 dbname=appdb user=appuser" -c 'SELECT current_user'

To check the stored hash type as a superuser, look at the beginning of rolpassword in pg_authid: SCRAM hashes start with SCRAM-SHA-256$. Setting the password again while password_encryption = 'scram-sha-256' (the default in recent versions) converts it.

SELECT rolname, left(rolpassword, 14) AS hash_prefix FROM pg_authid WHERE rolname = 'appuser';
SHOW password_encryption;

What not to do

Do not switch the pg_hba.conf line to trust to “make it work”. That lets anyone who reaches the server connect as that user with no password. If you need temporary access to reset a lost superuser password, prefer local peer authentication, and remove any temporary rule immediately afterwards.

Official documentation

• Authentication problems
• Password authentication
• CREATE ROLE