Postgres 28P01: password authentication failed

Fix PostgreSQL 28P01 password authentication failed by checking pg_hba.conf rules, password encoding, and connection string parameters.

intermediatedebuggingpostgresauthdatabase

Symptoms

FATAL: password authentication failed for user "app"
psql works locally but the application cannot connect
The error appears after a user password change or restore

Possible causes

The password in the connection string is wrong or contains unescaped special characters
pg_hba.conf selects a different auth method (md5/scram/peer) for this host
The role uses a different password than expected after a restore
An environment variable holding the password is not set in the runtime

Diagnosis steps

Read the pg_hba.conf lines matching your connection

SELECT * FROM pg_hba_file_rules;

Interpretation

The first matching rule decides the auth method and database; a peer or trust rule can change behaviour.

Verify the password directly with psql

PGPASSWORD=... psql -h host -U app -d db -c "SELECT 1"

Interpretation

If psql fails too, the credential or rule is wrong; if it works, the app is using a different string.

Check prisma/pooler parameters for escaping issues

Interpretation

Special characters in the password must be percent-encoded in a URL connection string.

Root cause

28P01 means the server rejected the supplied credential for that role and database after selecting an authentication method from pg_hba.conf. The password can be wrong, URL-encoded incorrectly, or the matching rule may require a method (peer, cert) that ignores the supplied password.

Fix

Set the password correctly with ALTER ROLE and ensure the connection string matches, percent-encoding special characters. Align pg_hba.conf so the host the app connects from uses password-compatible auth, then reload with SELECT pg_reload_conf(). Confirm environment variables are present in the actual runtime, not just your shell.

Verify the fix

Connect with the same credentials via psql and the application; both succeed, and pg_hba_file_rules shows the expected method for the app host.

Symptoms

Connections fail with FATAL: password authentication failed for user "app". It may work with psql on the server yet fail from the app host, which points at the auth rule or the connection string.

Diagnosis

Check the matching rule and test the credential directly:

PGPASSWORD='secret' psql -h db.internal -U app -d appdb -c 'SELECT 1'
SELECT * FROM pg_hba_file_rules;

Fix

Reset the password and align the rule:

ALTER ROLE app WITH PASSWORD 's3cret';
SELECT pg_reload_conf();

Percent-encode special characters in URL connection strings:

postgresql://app:p%[email protected]:5432/appdb

Verification

Connect via psql and from the application using the same credentials; both succeed, and pg_hba_file_rules lists a password-based method for the connecting host.

Why the Same Password Fails in One Place

PostgreSQL selects an authentication method from the first matching line in pg_hba.conf, which is a list of host, database, user, and method entries. A rule scoped to a low-priority host can leave your app host matching a different line that expects md5, scram-sha-256, or even peer. Adding a targeted, stronger rule above the general ones — limiting the app user and database to scram-sha-256 — is safer than loosening a broad rule. Reload the configuration without a restart so the change takes effect immediately, and confirm the winning line with pg_hba_file_rules rather than reading the file by eye.