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 myuser when you meant postgres produces this exact message.
  • The stored password hash doesn’t fit the method. A pg_hba.conf line with scram-sha-256 can’t verify a password that was stored as an MD5 hash (common on roles created before PostgreSQL 14 made scram-sha-256 the default password_encryption, or carried over by an upgrade) — the correct password fails. The reverse is fine: an md5 line 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.conf line to match. Lines are checked top to bottom and only the first match counts. (If the matching line is peer or ident, you’d see Peer authentication failed instead — 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_PASSWORD in a newer docker-compose.yml — the environment variable only takes effect on first initialization of an empty data directory.

How to fix it

  1. Identify which pg_hba.conf line actually matches your connection (type, database, user, address) and what method it specifies — local/peer entries behave very differently from host/scram-sha-256 ones.
  2. 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 current password_encryption, which fixes the MD5-vs-SCRAM mismatch. In psql, \password myuser does the same without sending the plain password in the SQL text.
  3. Double-check the username the client is actually sending — pass it explicitly (-U myuser) rather than relying on a default.
  4. 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 run ALTER ROLE against the running container instead of editing the compose file.
  5. After editing pg_hba.conf, reload it (SELECT pg_reload_conf(); or pg_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.

Related errors