psql "password authentication failed for user" — Bad Password or pg_hba.conf Rule?
Four root causes of psql password authentication failed: incorrect password, md5/SCRAM mismatch, pg_hba.conf rule ordering, and port/cluster confusion. Step-by-step triage.
Operational Verification & Reliability Metadata
The error string is a symptom, not the root cause. Do not restart the server blindly. Run the diagnostic queries below to pinpoint the actual failure mode.
▸Symptom
FATAL: password authentication failed for user "postgres"PostgreSQL intentionally obscures authentication failure details to prevent user enumeration. The error can stem from an outdated password hash algorithm, unmatched pg_hba.conf rules, or cached credentials.
▸Key Diagnostic Steps
1. Inspect hash storage:
SELECT rolname, left(rolpassword, 14) AS hash_type FROM pg_authid WHERE rolname = 'postgres';2. Check effective pg_hba rules:
SELECT rule_number, type, database, user_name, address, auth_method FROM pg_hba_file_rules ORDER BY rule_number;3. Reset password using SCRAM-SHA-256:
SET password_encryption = 'scram-sha-256';
ALTER USER postgres WITH PASSWORD 'your-strong-password';- •PostgreSQL Security Hardening CheatSheet
- •Validated versions: PostgreSQL 14 / 15 / 16 / 17
Other Database Error Triage Playbooks
Other battle-tested diagnostic guides for high-severity database errors.
PostgreSQL too many clients already: 6-Step Resolution
Three root causes of FATAL: sorry, too many clients already, single diagnostic query to identify the cause, and permanent mitigation via max_connections and PgBouncer.
PostgreSQL connection refused: 8-Step Definitive Triage
Difference between connection refused, timeout, and no pg_hba entry; triage for listen_addresses, port conflicts, firewalls, and Docker container mappings.
PostgreSQL duplicate key Error: Sequence Sync Fix
Root cause of duplicate key violations after restore or bulk migration, one-line setval repair, and an automated schema-wide PL/pgSQL DO block.