What the message looks like
psql: error: connection to server at "127.0.0.1", port 5432 failed: FATAL: password authentication failed for user "appuser"
2026-10-12 09:14:03 CEST [4121] FATAL: password authentication failed for user "appuser"
2026-10-12 09:14:03 CEST [4121] DETAIL: Connection matched pg_hba.conf line 113: "host all all 127.0.0.1/32 scram-sha-256"Common causes
- The password is wrong, for example an old one in the app config, in an environment variable or in
~/.pgpass. - The role has no password set, or it was set in a different way than the line expects.
- Another
pg_hba.confline matches first. The first match wins, so a different user, database, address or method may apply. - Special characters in the password break a connection URL, such as
@,:,/or%, and must be percent-encoded. - The user name has other spelling or case than the role in the database.
Check
- Which roles exist and can log in?
sudo -u postgres psql -c '\du' - Which line did the failed login match? Read the DETAIL in the log
sudo tail -n 30 /var/log/postgresql/postgresql-*-main.log - Active rules in order
sudo -u postgres psql -c 'SELECT line_number, type, database, user_name, address, auth_method FROM pg_hba_file_rules' - Password encryption in use
sudo -u postgres psql -c 'SHOW password_encryption'
Fix
- Set a new password interactively so it does not land in the shell history:
sudo -u postgres psql, then\password appuser. - Use the same password in the app config. Percent-encode special characters in a URL or switch to separate host, user and password parameters.
- Fix the order and content of the
pg_hba.conflines, then reload:sudo systemctl reload postgresql. Never usetrustfor network addresses as a quick fix. - If an old client library supports only md5, update the library rather than lowering the security of the server. After changing
password_encryption, set the passwords again. - Remove an outdated
~/.pgpassentry orPGPASSWORDvariable that overrides the password you think you use.
Typical scenario
An application in a Docker container connects with postgres://app:p@ss/word@db:5432/appdb. The password p@ss/word contains an @ and a slash, the URL is parsed wrongly, and PostgreSQL reports "password authentication failed for user". The server log additionally has the line "Connection matched pg_hba.conf line …" and the reason. Read those two lines first; they tell you which rule applied and why the password was rejected.
FAQ
Why does psql work on the server but not from the app?
Locally, the socket often uses another rule (peer) than the network (scram-sha-256). Test with psql -h 127.0.0.1 to use the same path as the app.
How is this different from no pg_hba.conf entry?
Here a line matched and the password failed. With “no pg_hba.conf entry” no line matched at all, so the server rejects before asking for a password.
Where do I find the exact reason in the log?
In the server's log file, usually under /var/log/postgresql/. The FATAL is followed by a DETAIL line with the reason, for example "Password does not match for user", "Role does not exist" or "User has no password assigned". For security reasons the client only gets the general message.
Which characters do I have to encode in a URL?
Special characters are percent-encoded: @ becomes %40, / becomes %2F, : becomes %3A and % becomes %25. So p@ss/word turns into p%40ss%2Fword. It is simpler to pass host, user and password as separate parameters if the library allows it.
Why do old clients fail with scram-sha-256 after a password change?
Since PostgreSQL 14 the server stores new passwords as SCRAM hashes by default. Very old client libraries, such as libpq before version 10, do not support SCRAM. Then updating the library helps, or you deliberately store the password as md5, which is not recommended.