About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
FATAL: password authentication failed for user "appuser" is what the client sees when a pg_hba.conf record using the password, md5 or scram-sha-256 method matched and the login did not succeed. The client message is deliberately the same for every cause. The server log carries the detail: the role does not exist, it has no password, the password has expired, the password does not match, and which line of pg_hba.conf matched. Read the log before you reset anything.
What the error means
In the PostgreSQL source (REL_17_STABLE and REL_19_STABLE), the same message text, password authentication failed for user "%s", is used for the three password methods: password, md5 and scram-sha-256. Other methods have their own wording, for example Peer authentication failed for user "%s" and Ident authentication failed for user "%s". If you see one of those, the record that matched is not a password record, and the advice here does not apply.
The detail goes to the server log only. The source adds a line of the form Connection matched file "%s" line %d: "%s", and, from the password lookup, one of these:
Role "%s" does not exist.User "%s" has no password assigned.User "%s" has an expired password.Password does not match for user "%s".User "%s" does not have a valid SCRAM secret.(from the SCRAM code, when the stored password is an MD5 hash and the record asks forscram-sha-256)
The source holds two further details for stored passwords that the method cannot use: User "%s" has a password that cannot be used with MD5 authentication. and Password of user "%s" is in unrecognized format.
A comment in the source explains why the client sees nothing more: when the user does not exist, has no password, or has an expired one, the server still goes "through the motions of authentication, to avoid revealing to the client that the user didn't exist". So the client message cannot tell you whether the role exists. Only the log can.
The PostgreSQL documentation adds three facts about stored passwords:
- "If no password has been set up for a user, the stored password is null and password authentication will always fail for that user."
- The
password_encryptionsetting decides how a password is stored when it is set, and its default isscram-sha-256; the other value ismd5. - "If a password was encrypted using the md5 setting, then it can be used only for the md5 and password authentication method specifications". A password stored with
scram-sha-256can be used forscram-sha-256,passwordand, becausemd5then switches to SCRAM automatically,md5.
So a role whose password was created under md5 fails against a scram-sha-256 record, even if the person types the right password.
Likely causes
| Cause | What you see in the server log | How to confirm |
|---|---|---|
| Wrong password typed or saved in the client | Password does not match for user "appuser". |
Check .pgpass and the application's settings |
| Role does not exist (wrong name, different server) | Role "appuser" does not exist. |
In psql, \du appuser lists matching roles (the pg_roles query in step 2 also shows none) |
| Role has no password | User "appuser" has no password assigned. |
pg_authid shows a null rolpassword |
| Password expired | User "appuser" has an expired password. |
rolvaliduntil in pg_roles is in the past |
Stored as md5, record says scram-sha-256 |
User "appuser" does not have a valid SCRAM secret. The password may be correct, but the login fails |
rolpassword starts with md5; record method in pg_hba_file_rules |
| Client sends an old saved password | Works at a prompt, fails from the application | Check the password file and environment of the client |
| Wrong server or record | The Connection matched file line names a record you did not expect |
Compare with pg_hba_file_rules |
Prove the cause before changing anything
All of these are read-only.
1. Read the server log line for the failed attempt. Look for the password authentication failed line, the detail line beneath it, and the Connection matched file ... line ... line. The detail line is one of the details listed above. The matched line tells you which pg_hba.conf record, and so which method, was used.
2. Check the role. As a superuser:
SELECT rolname, rolcanlogin, rolvaliduntil FROM pg_roles WHERE rolname = 'appuser';
The pg_roles view has rolcanlogin and rolvaliduntil columns. A past rolvaliduntil explains an expired password.
3. Check how the password is stored. The documentation says: "To check the currently stored password hashes, see the system catalog pg_authid", that an MD5 value "will begin with the string md5 followed by a 32-character hexadecimal MD5 hash", and that a SCRAM value has the format SCRAM-SHA-256$ followed by iteration count, salt and keys. This query shows the type without printing the hash:
SELECT rolname,
rolpassword IS NULL AS no_password,
rolpassword LIKE 'md5%' AS stored_md5,
rolpassword LIKE 'SCRAM-SHA-256$%' AS stored_scram
FROM pg_authid WHERE rolname = 'appuser';
4. Check the rules.
SELECT rule_number, line_number, type, database, user_name, address, auth_method FROM pg_hba_file_rules;
Find the line the log named and read its auth_method.
5. Check the client. The libpq documentation says the .pgpass file in a user's home directory holds passwords in the form hostname:port:database:username:password, that "The password field from the first line that matches the current connection parameters will be used", and that on Unix "If the permissions are less strict than this, the file will be ignored." A stale first line can supply an old password without anyone noticing.
Fix
Wrong or stale client password
Correct the application's setting or the matching line of the password file. Nothing on the server changes.
Missing, expired or md5-stored password
Setting a new password changes the role. Disruptive step: every client that still uses the old password will fail until it is updated, and the old password cannot be restored from the server. Before you change anything, run the SELECT in step 2 for the exact role and keep its output (login flag and expiry). The documentation recommends the psql \password command, because ALTER ROLE with a password "will be transmitted to the server in cleartext, and it might also be logged in the client's command history or the server log". Connect as a superuser and run:
\password appuser
With password_encryption at its default of scram-sha-256, the new password is stored as SCRAM, which suits both scram-sha-256 and md5 records. If step 2 showed a past rolvaliduntil, set a new expiry as well with ALTER ROLE appuser VALID UNTIL 'date';, using a date chosen by your policy and run after you have kept the step 2 output, then run the step 2 query again to check the value. To back out of the expiry change, run ALTER ROLE appuser VALID UNTIL 'date'; again with the old rolvaliduntil value from the step 2 output you kept, and run the step 2 query once more to compare. (The ALTER ROLE page gives ALTER ROLE fred VALID UNTIL 'infinity'; as the form that makes a password valid forever, which is a different decision.) To back out of a password change, set the password back to the value the clients hold, with the same command. If you do not know it, update the clients.
Missing role
If the log says the role does not exist, create it with the options your application needs. The CREATE ROLE page's examples include CREATE ROLE jonathan LOGIN;; set its password afterwards with \password, as above, so the password is not typed into a command that can be logged. Check that you are on the right server first; a restore may not carry roles with it, which "A PostgreSQL Dump Restored with Missing Roles or Extensions: Check the Recovery Set" covers.
Do not loosen the rule to make it pass
Changing a scram-sha-256 record to md5 or password to suit an old client weakens the setup. The documentation warns that password "sends the password in clear-text", and that MD5 password support "is deprecated and will be removed in a future release". If an old client library cannot do SCRAM, the documentation says the method "is not supported by older client libraries", so update the library.
Editing pg_hba.conf and reloading it is a Disruptive step because the reload applies the file to all new connections. If you must edit pg_hba.conf, find its path with SHOW hba_file; (the File Locations page documents hba_file) and save it first, for example cp /srv/pgdata/pg_hba.conf /srv/pgdata/pg_hba.conf.saved-20261120 (the path is an example). Check the result with pg_hba_file_rules, then reload with SELECT pg_reload_conf();. To back out, run cp /srv/pgdata/pg_hba.conf.saved-20261120 /srv/pgdata/pg_hba.conf, check it with pg_hba_file_rules, and reload again.
Example (illustrative): After a move to db01, the application shop-web fails with password authentication failed for user "appuser". The log says User "appuser" does not have a valid SCRAM secret. and Connection matched file ... line 9. Line 9 is a scram-sha-256 record. The pg_authid query shows stored_md5 is true, because the role came from an old server that stored MD5. The administrator saves the role's settings, runs \password appuser as a superuser, and updates the application's secret. The login works.
Confirm the fix
- The client connects and runs a simple query as the role.
- The server log shows no new
password authentication failedlines for it. - The
pg_authidquery now showsstored_scramas true. - Other applications that share the role still connect, or have been updated.
What to watch afterwards
- Alert on repeated authentication failures from one address; they may be a stale credential or an attack.
- Keep a record of which applications use which role before you change a password.
- Follow the documented path off MD5: set
password_encryption = 'scram-sha-256', have users set new passwords, then changepg_hba.confrecords toscram-sha-256. - Check
rolvaliduntilon login roles before it passes.
Read next
Related articles you may want next.
- TroubleshootingPostgreSQL "no pg_hba.conf entry for host": write the rule that matches, then reloadPostgreSQL 'no pg_hba.conf entry for host'? Read the host, user, database and encryption in the message, add a matching record, check it, then reload.Read article
- Backup & RecoveryA PostgreSQL Dump Restored with Missing Roles or Extensions: Check the Recovery SetInventory database content, cluster-wide objects and extension packages needed for a usable logical restore.Read article
- TroubleshootingPostgreSQL "Connection refused" on port 5432: listen_addresses, the service and the firewallPostgreSQL 'Connection refused' on port 5432? Check the service, listen_addresses (default localhost) and the port, then the network path.Read article
Risks and limits
- These commands have not been run or lab-tested.
- Message text is from REL_17_STABLE and REL_19_STABLE; other releases can differ.
- The
pg_authidpage says only that the catalog "must not be publicly readable"; run the query as a superuser. - The log detail for an md5-stored password under a
scram-sha-256record is read from the SCRAM source file of branch REL_19_STABLE only; wording in other releases can differ. - Methods other than
password,md5andscram-sha-256are not covered.
Sources
- PostgreSQL 19: Password Authentication — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: The pg_hba.conf File — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: pg_authid — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: pg_roles — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: pg_hba_file_rules — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: ALTER ROLE — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: CREATE ROLE — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: File Locations — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: Connection Settings (password_encryption) — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: The Password File — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: psql — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL 19: Server Signaling Functions — PostgreSQL documentation, version 19, no date shown, accessed 20 November 2026
- PostgreSQL REL_19_STABLE source: auth.c — PostgreSQL project, branch REL_19_STABLE, no date shown, accessed 20 November 2026
- PostgreSQL REL_19_STABLE source: crypt.c — PostgreSQL project, branch REL_19_STABLE, no date shown, accessed 20 November 2026
- PostgreSQL REL_19_STABLE source: auth-scram.c — PostgreSQL project, branch REL_19_STABLE, no date shown, accessed 20 November 2026
- PostgreSQL REL_17_STABLE source: auth.c — PostgreSQL project, branch REL_17_STABLE, no date shown, accessed 20 November 2026
- PostgreSQL REL_17_STABLE source: crypt.c — PostgreSQL project, branch REL_17_STABLE, no date shown, accessed 20 November 2026
This article was originally published on .