// PostgreSQL error reference

PostgreSQL 28P01: password authentication failed

PostgreSQL rejected the password for this user. A wrong password, a role without a password, or a password hashed in a format the server no longer accepts.

SQLSTATE
28P01
Name
invalid_password
Category
Invalid Authorization Specification
Error message
password authentication failed for user "app"

What it means

The server found a pg_hba.conf rule that asks for a password (scram-sha-256, md5 or password) for this connection, and the password the client sent didn't match the role's stored password.

For security the client is only told the password failed. The server log has the reason, for example User "app" has no password assigned or Role "app" does not exist.

Common causes

  • Wrong password, or a password with special characters mangled in a connection URL (they must be percent-encoded).
  • The role doesn't exist or has no password set; the client still sees password authentication failed.
  • The role's password is stored as an MD5 hash but pg_hba.conf requires scram-sha-256, after an upgrade to a default of SCRAM.
  • The client picked up a different password from PGPASSWORD or a .pgpass file.

How to fix it

  1. Read the server log entry for the failed login; it states the real reason.

  2. Set a new password as a superuser (in psql, \password app prompts without echoing it).

    ALTER ROLE app WITH LOGIN PASSWORD 'new-strong-password';
  3. Check how the password is stored. A value starting with md5 must be reset after switching password_encryption to scram-sha-256.

    SHOW password_encryption;
    SELECT rolname, left(rolpassword, 14) AS hash_type
    FROM pg_authid WHERE rolname = 'app';
  4. Check which pg_hba.conf line matched; the view shows the file as the server loaded it.

    SELECT line_number, type, database, user_name, address, auth_method
    FROM pg_hba_file_rules;
  5. Percent-encode special characters in connection URLs, for example @ as %40: postgresql://app:p%40ss@db:5432/shop.

Related errors

The code and message text are from the PostgreSQL documentation, Appendix A: PostgreSQL Error Codes. Browse the full PostgreSQL error list or search every database error.

// fewer errors, faster fixes

Work on PostgreSQL in SQLly

A native SQL client for macOS, Windows and Linux with schema-aware IntelliSense, guardrails for risky statements and clear error messages, for PostgreSQL and the other databases you use.