PostgreSQL error: password authentication failed for user

SQLSTATE 28P01 (invalid_password) · Updated July 9, 2026

psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL:  password authentication failed for user "app_user"

You reached the server, pg_hba.conf selected a password-based authentication method for this connection, and the password check failed. The client message is deliberately vague; the server log usually says more.

What this error means

The client is told only "authentication failed" — that's intentional, to avoid leaking information to attackers. The server log, however, records the underlying reason at the same timestamp: the role having no password assigned, the password not matching, or the stored password format not being usable with the authentication method pg_hba.conf demands.

That last one deserves a word: passwords are stored hashed, using the algorithm that password_encryption had when the password was set (scram-sha-256 on modern versions, md5 historically). Changing password_encryption or the pg_hba method does not convert existing stored passwords — mismatches surface as failed logins for passwords that are "definitely right".

Common causes

• Wrong password or wrong user — including "right password, wrong environment": staging credentials against production, or a Docker port mapping pointing at a different instance than you think.
• The role has no password set (created with CREATE ROLE and never given one). Any password fails; only the server log says why.
• SCRAM/md5 mismatch: password stored as md5 while pg_hba requires scram-sha-256, or a very old client library that doesn't speak SCRAM.
• Special characters in a connection URI (@, :, /, # in the password) not percent-encoded, so the parsed password isn't what you typed.

How to diagnose it

• Read the server log at the timestamp of the failure — it almost always names the real cause.
• Check which pg_hba rule the connection matches: SELECT * FROM pg_hba_file_rules; shows the parsed rules in order (first match wins).
• Test with psql directly, taking the application, URI parsing and pooler out of the equation: psql "host=... user=app_user dbname=appdb" and type the password interactively.

How to fix it

• Reset the password — prefer psql's \password over a plain SQL statement, so the new password doesn't end up in the server log or shell history:

  \password app_user

• Align the stack on SCRAM: set password_encryption = 'scram-sha-256', use scram-sha-256 in pg_hba.conf, and re-set every password after the change so the stored hashes match.
• Percent-encode passwords in URIs, or pass the password via PGPASSWORD/.pgpass/connection parameters instead of the URI.