PostgreSQL Error 28P01

SQLSTATE

28P01

Condition name

invalid_password

Product

PostgreSQL

Versions

PostgreSQL 13 to 18

Category

Connections, Authentication & Privileges

Last reviewed

24 October 2026

What it means

SQLSTATE 28P01 means the server reached the password check for this login and the check failed: a wrong, missing or expired password, or a password stored in a form the pg_hba.conf method cannot use.

When a client connects, PostgreSQL picks the first matching line in pg_hba.conf. If that line uses a password method (scram-sha-256, md5 or password), the server asks for a password and checks it against the role's stored password in pg_authid. If the check fails, the login ends with FATAL: password authentication failed for user "..." and SQLSTATE 28P01 (invalid_password). As the documentation puts it, the server is willing to talk to you, but not until you pass the authentication method in pg_hba.conf.

The client is deliberately told very little. The same message appears when the password is wrong, when the role has no password (then password authentication always fails), when its VALID UNTIL time has passed, and even when the role does not exist, so that an attacker cannot use the message to discover role names. The documentation's advice: the server log contains more information than the client gets, so read it when the reason is unclear. psql and other libpq programs print the server message after their own connection to server ... failed: prefix.

Common causes

• The password in the connection string, environment variable (PGPASSWORD), .pgpass file or application secret is wrong or out of date after a rotation.
• The role has no password set (common for roles created without PASSWORD, or the postgres role on a fresh install that used peer authentication locally).
• The role's VALID UNTIL time has passed, so its password is no longer accepted.
• The password is stored as an MD5 hash but the matching pg_hba.conf line requires scram-sha-256, which an MD5-hashed password cannot satisfy.
• The client connects as a different role than intended (a typo, a default user name, or a pooler that rewrites the user), or the role does not exist at all.

Diagnose it

Read-only These queries only read the system catalogs (pg_catalog, information_schema) and statistics views such as pg_stat_activity and pg_locks. They do not change data, roles or settings, so they are safe to run first.

SELECT rolname, rolcanlogin, rolvaliduntil,
       rolvaliduntil < now() AS password_expired
FROM pg_roles
WHERE rolname = 'andym';

SELECT rolname,
       rolpassword IS NOT NULL AS has_password,
       rolpassword LIKE 'SCRAM-SHA-256$%' AS is_scram
FROM pg_authid
WHERE rolname = 'andym';

SELECT current_setting('password_encryption') AS password_encryption;

SELECT rule_number, line_number, type, database, user_name,
       address, netmask, auth_method, error
FROM pg_hba_file_rules
ORDER BY rule_number;

How to fix it

Each fix is labelled with what it changes. Try read-only checks and the least invasive fix first, and test changes outside production.

-- in psql, connected as a superuser or a role with CREATEROLE:
\password andym

-- or, from any client:
ALTER ROLE andym PASSWORD 'a-long-random-password';

ALTER ROLE andym VALID UNTIL '2027-06-30';

CREATE ROLE andym LOGIN PASSWORD 'a-long-random-password';
GRANT CONNECT ON DATABASE testdb TO andym;

Examples

Logging in over TCP with a wrong password

Shown as documented in the PostgreSQL documentation (Client Authentication, Authentication Problems). This example needs a running PostgreSQL server (a login over TCP that matches a password rule in pg_hba.conf), which PGlite does not provide, so it was not reproduced here.

-- From a shell on the client machine:
-- psql "host=server.joe.com port=5432 dbname=testdb user=andym"
-- Password for user andym:   (a wrong password is typed)

FATAL:  password authentication failed for user "andym"

A role whose password has expired

The message is the documented one (Client Authentication, Authentication Problems): the client is not told that the password expired, only the server log says so. This example needs a running PostgreSQL server (a password login after the VALID UNTIL time), which PGlite does not provide, so it was not reproduced here.

-- As an administrator:
CREATE ROLE andym LOGIN PASSWORD 'secret' VALID UNTIL '2026-01-01';

-- Later, from the client:
-- psql "host=server.joe.com dbname=testdb user=andym"   (correct password)

FATAL:  password authentication failed for user "andym"

How to prevent it

Keep each application's password in one secret store that every instance reads, rotate it by setting the new password and updating all consumers together, and avoid hard-coded passwords and stray .pgpass lines. Use scram-sha-256 in pg_hba.conf and password_encryption, and set any MD5-hashed passwords again so they are stored as SCRAM.

If you use VALID UNTIL, monitor rolvaliduntil so passwords are renewed before they expire. Watch the server log for repeated failures from one address; they can point to a misconfigured client or to password guessing.

Common questions

Learn more on CodeWithSQL

• Install PostgreSQL
• Run PostgreSQL in Docker

Official documentation

• Authentication problems
• Password authentication
• The password file (.pgpass)
• ALTER ROLE

Last technically reviewed 24 October 2026; examples and diagnostics run on PostgreSQL 18.6 documentation; SQL-level parts in PGlite 0.5.11. SQL-level examples were run in PGlite (PostgreSQL compiled to WebAssembly); examples that need a running server are shown as documented in the PostgreSQL documentation.