PostgreSQL: 'FATAL: password authentication failed for user "postgres"' (SQLSTATE 28P01) even though the password looks right. How do I fix it?

Cause: the server matched your connection to a pg_hba.conf rule that requires a password (scram-sha-256 or md5), and the password check failed. Common reasons: - The role really has a different password, or none was ever set (the postgres role often has no password on fresh Linux installs and only works through local 'peer' authentication). - You're connecting to a different server than you think: a second PostgreSQL install on the same port, a Docker container whose data volume was created with an older POSTGRES_PASSWORD (the env var only applies when the data directory is first initialized), or the wrong host/port in the connection string. - An old client library or driver that doesn't support SCRAM, or a password hash stored as md5 while clients or poolers (PgBouncer) expect SCRAM, or the reverse. - Special characters in the password that aren't URL-encoded in a connection URI. How to check: - Read the server log: it prints which pg_hba.conf line matched and often 'User "x" has no password assigned' or 'Password does not match'. - SHOW hba_file; and SHOW password_encryption; as a superuser; SELECT rolname, rolpassword IS NOT NULL FROM pg_authid WHERE rolname = 'postgres'; Fix: 1. Log in as the OS postgres user through peer auth (sudo -u postgres psql) or docker exec into the container, and set the password: \password postgres (avoids putting the password in shell history). 2. Make sure password_encryption is scram-sha-256 (the default since PostgreSQL 14) and pg_hba.conf host lines use scram-sha-256; re-set passwords that were stored as md5. Reload with SELECT pg_reload_conf(); 3. For Docker: if the volume already exists, changing POSTGRES_PASSWORD does nothing; set the password with ALTER ROLE inside the container, or recreate the volume if the data is disposable. 4. URL-encode special characters in connection URIs, and upgrade old drivers to versions with SCRAM support. After: connect again with psql "host=... user=... dbname=..." from the same machine as the app, and keep pg_hba.conf host rules limited to the networks that need access. Sources: https://www.postgresql.org/docs/current/auth-password.html https://www.postgresql.org/docs/current/auth-pg-hba-conf.html https://hub.docker.com/_/postgres