PostgreSQL
FATAL: password authentication failed for user "postgres"
FATAL: password authentication failed for user — why pg_hba.conf, the wrong password, or the wrong database user cause it, and how to fix each.
What it means
PostgreSQL rejected the login because the password didn’t match what’s stored for that user, under the authentication method that pg_hba.conf assigned to this specific connection. pg_hba.conf is checked top to bottom; the first line whose connection type, database, user and address all match is the one used, and if authentication fails against that method, PostgreSQL does not fall through to try another line — it returns this error and the client never gets a second attempt inside the same connection.
Common causes
- The password is genuinely wrong — including trailing whitespace pasted from a script, or a password containing characters that a shell or connection string ate (an unescaped
@or$, for instance). - The role you’re connecting as isn’t the role you think you are. Many client libraries default to your OS username if none is given; connecting as
myuserwhen you meantpostgresproduces this exact message. - The stored password hash doesn’t fit the method. A
pg_hba.confline withscram-sha-256can’t verify a password that was stored as an MD5 hash (common on roles created before PostgreSQL 14 madescram-sha-256the defaultpassword_encryption, or carried over by an upgrade) — the correct password fails. The reverse is fine: anmd5line automatically uses SCRAM for a SCRAM-stored password. - The role has no password at all (
NULL), which always fails password authentication. - You expected a different
pg_hba.confline to match. Lines are checked top to bottom and only the first match counts. (If the matching line ispeerorident, you’d seePeer authentication failedinstead — a different error with a different fix.) - Running inside Docker or Docker Compose, where the password baked into an already-initialized data volume no longer matches
POSTGRES_PASSWORDin a newerdocker-compose.yml— the environment variable only takes effect on first initialization of an empty data directory.
How to fix it
- Identify which
pg_hba.confline actually matches your connection (type, database, user, address) and what method it specifies —local/peerentries behave very differently fromhost/scram-sha-256ones. - Reset the password from an account that can already connect (e.g. locally, via
peer):ALTER ROLE myuser WITH PASSWORD 'newpassword';— this also re-hashes it with the currentpassword_encryption, which fixes the MD5-vs-SCRAM mismatch. Inpsql,\password myuserdoes the same without sending the plain password in the SQL text. - Double-check the username the client is actually sending — pass it explicitly (
-U myuser) rather than relying on a default. - If it’s a Docker Compose setup and the volume already existed before you changed
POSTGRES_PASSWORD, either remove the volume and let it reinitialize (if the data is disposable) or runALTER ROLEagainst the running container instead of editing the compose file. - After editing
pg_hba.conf, reload it (SELECT pg_reload_conf();orpg_ctl reload) — it isn’t re-read automatically on every connection.
In Tablyne
Once you connect successfully, Tablyne stores the password in your OS keychain, so you only need to re-enter it if the account’s actual password changes — not on every session.
Stop re-typing connection strings. Download Tablyne or open the Postgres GUI.
Sources
Frequently asked questions
I'm sure the password is right — why does it still fail? +
Check how the password is stored. If pg_hba.conf asks for scram-sha-256 but the role's password was saved as an MD5 hash (set before password_encryption became scram-sha-256 in PostgreSQL 14, or carried over by an upgrade), the right password still fails; the server log shows 'User does not have a valid SCRAM secret'. Setting the password again fixes it. Also confirm you're connecting as the user you think you are — a client defaulting to your OS username is a common surprise.
Does this error mean the account doesn't exist? +
Not necessarily. PostgreSQL deliberately returns the same 'password authentication failed' message whether the user exists with a wrong password or doesn't exist at all, so an attacker can't use the error to enumerate valid usernames.
Why does the same connection work with psql on the server but fail from another machine? +
Local connections often match a 'trust' or 'peer' record in pg_hba.conf that skips password checking entirely. A remote connection matches a different record — typically one requiring scram-sha-256 or md5 — where the same password now actually gets verified, and a mismatch shows up for the first time.