Incident brief
Invalid password
A connection attempt supplied the wrong password for a password-authenticated role. PostgreSQL rejected the connection before it was ever established.
In 10 seconds
- What triggers it
- Connect with a role that requires password authentication (not trust).
- Fix
- Reconnect with the correct password.
- Proof
- Reproduced on PostgreSQL 16.14 → Connecting with the wrong password, over a network path that genuinely enforces password authentication, was rejected with SQLSTATE 28P01. The correct password, tried right afterward, succeeded.
Fix
What to do right now
Application-level steps for this error.
- Reconnect with the correct password.
- Reset the role's password with ALTER ROLE ... PASSWORD if it's genuinely been lost, rather than working around authentication.
- Never 'fix' this by adding a trust rule to pg_hba.conf, see the counterexample for exactly what that gives up.
-- Fix is operational: set a real password / use scram, or correct the client secret.
-- Lab-safe proof the server accepts a valid login role after CREATE ROLE:
DO $$ BEGIN
CREATE ROLE lab_auth_ok LOGIN PASSWORD 'correct-horse-battery';
EXCEPTION WHEN duplicate_object THEN
ALTER ROLE lab_auth_ok PASSWORD 'correct-horse-battery';
END $$;
SELECT rolname FROM pg_roles WHERE rolname = 'lab_auth_ok';For this error
See this error live on the server
Run these against the affected instance to confirm the diagnosis before you act.
Authentication fails before a normal backend query runs. Check role validity and the parsed HBA rule, then verify the corrected secret from the same network path as the application.
Role login and expiry
Replace the role literal from the FATAL message; PostgreSQL never exposes the stored password itself.
SELECT rolname, rolcanlogin, rolvaliduntil,
rolconnlimit
FROM pg_roles
WHERE rolname = '<role_from_error>';Parsed pg_hba.conf rules
Confirm the rule order and authentication method PostgreSQL actually parsed.
SELECT rule_number, type, database, user_name, address, auth_method, error
FROM pg_hba_file_rules
ORDER BY rule_number;Why it happens
What PostgreSQL is telling you
The mechanism behind the error, grounded in the official manual, not paraphrased.
PostgreSQL 16 Documentation, Password Authentication
If no password has been set up for a user, the stored password is null and password authentication will always fail for that user.Read the full section on postgresql.org →
Wrong password
The role postgres requires password authentication on this connection path, and the supplied password did not match, PostgreSQL rejects the connection outright, before any query can run.Correct password, right afterward
The identical connection, with only the password corrected, succeeded immediately, confirming the earlier failure was specifically about the password, not the host, port, role, or database name.Reproduce & verify
A real reproduction over a password-authenticated connection
A literal transcript of SQL run against a live PostgreSQL instance in an isolated lab. The commands below are exactly what was executed.
- 1Connect with a role that requires password authentication (not trust).
- 2Supply the wrong password.
- 3SQLSTATE 28P01 is reported as a FATAL connection error; no session is ever established.
One client, tried twice: first with a wrong password, then with the correct one, both against the same password-authenticated network path.
-- No schema needed: this reproduces at the connection/authentication stage, before any query runs.
SELECT 'no schema required' AS setup_note;psql "host=<db-host> user=postgres password=wrong-password dbname=<app-db>"psql "host=<db-host> user=postgres password=<correct-password> dbname=<app-db>" -c "SELECT 1 AS connected_successfully;"What PostgreSQL actually returned
setup_note
--------------------
no schema required
(1 row)psql: error: connection to server at "<db-host>", port 5432 failed: FATAL: password authentication failed for user "postgres" connected_successfully
-------------------------
1
(1 row)It's easy to assume repeated failed password attempts eventually lock an account, the way many web apps do. This was tested directly: five wrong-password attempts in a row, then the correct password tried immediately after.
Without this
Above: a single wrong password is rejected with SQLSTATE 28P01.
With this, tested
Below: after five wrong attempts in a row, the correct password still works immediately, with no extra delay or lockout.
- A second operational test: exact SQL, raw output, measured result, and engineer notes
- Fix that removes authentication instead of repairing it: exact SQL, output, and verdict
- A manual-grounded production interpretation of the lab result
Card required. Cancel before day 7 and you are not charged.
Runbook to fix this
The runbook for this incident
Full step-by-step fixes for the condition behind this error: the diagnosis, the exact SQL, and output captured in the lab.
Connected
Everything this error touches
Every page this SQLSTATE connects to: the concept that explains it, the runbooks that fix it, the parameters you tune to prevent it, and the sibling errors it travels with. All real cross-references. Jump straight in, or open the full interactive map.
Fix it — runbooks
Verification
- Last verified
- 2026-07-16 (Docker lab, PostgreSQL 16.14)
- Verification scope
- Verified against PostgreSQL 16.14 in an isolated lab environment
- Audit status
- reviewed
Went further?
Pro unlocks the second lab proof
Free page stops the bleeding. Pro adds the operational test, SQLSTATE audit, and deeper evidence, same error, more certainty.