Likely causes
- •Wrong password in the connection string. The most common cause. The password in your app config, .env file, or DBeaver connection profile does not match the one stored in PostgreSQL. Reset the password to a known value using ALTER USER (see the fix steps) and update every place that credential is referenced.
- •Password was changed and the application was not updated. Someone ran ALTER USER or ALTER ROLE to rotate credentials but did not update the app's environment variables or secrets manager. Look for a recent password change in the PostgreSQL log: search for ALTER ROLE near the time the errors started.
- •Mismatch between the auth method in pg_hba.conf and the hash stored for the role. If pg_hba.conf specifies scram-sha-256 but the role's password was last set while password_encryption was md5 (or vice versa), the stored hash is in the wrong format and authentication fails even with the correct password. The fix is to reset the password after aligning password_encryption in postgresql.conf, so PostgreSQL stores a new hash in the expected format.
- •Connecting as the wrong role. The username in the connection string does not exist in PostgreSQL, or the role name has a typo. Run SELECT rolname FROM pg_roles; as a superuser to list all roles and confirm the target role is present.
- •The postgres superuser has no SQL password set. By default the postgres superuser relies on peer or ident auth and may have no SQL password assigned. Connecting from a remote host or from DBeaver forces password auth, which then fails because no password exists. Assign one with ALTER USER postgres WITH PASSWORD '...' and ensure pg_hba.conf allows password-based auth for that connection path.
- •pg_hba.conf line order places a reject or more specific rule above the matching rule. PostgreSQL reads pg_hba.conf top to bottom and uses the first matching line. A reject rule earlier in the file for the same user/database/address combination will block the connection before it reaches the password-auth line.
How to fix it
1. Check the PostgreSQL log for the full error line
The log usually names the database, the user, the client address, and the auth method that was tried. This narrows down the cause before you change anything.
sudo journalctl -u postgresql --since '30 minutes ago' | grep 'authentication failed' # Or for file-based logging: sudo tail -n 100 /var/log/postgresql/postgresql-*.log | grep 'authentication failed'2. Confirm the role exists in PostgreSQL
Log in via peer auth as the postgres OS user (this bypasses password auth) and list roles.
sudo -u postgres psql -c "SELECT rolname, rolcanlogin FROM pg_roles WHERE rolname = 'your_user';"3. Reset the role's password to a known value
If the role exists but the password is unknown or stale, reset it. Use a strong password in production. This change takes effect immediately with no restart needed.
sudo -u postgres psql -c "ALTER USER your_user WITH PASSWORD 'new_password';"4. Check and align the auth method in pg_hba.conf
Open pg_hba.conf and find the line for your user, database, and connection type. The method should match what the client supports. For PostgreSQL 14 and later, scram-sha-256 is preferred. For older clients that do not support SCRAM, use md5.
sudo grep -n 'your_user\|all' /etc/postgresql/*/main/pg_hba.conf # Ubuntu/Debian path shown; on RHEL/AlmaLinux/Rocky it is usually: # /var/lib/pgsql/data/pg_hba.conf or /var/lib/pgsql/16/data/pg_hba.conf5. Verify password_encryption matches the auth method in pg_hba.conf, then reset the password
If you change the auth method in pg_hba.conf, also check that password_encryption in postgresql.conf matches it, then reset the role's password again. PostgreSQL stores the hash in the format that password_encryption specifies at the moment ALTER USER is run. If the stored hash and the pg_hba.conf method do not match, authentication will fail even with the correct password.
sudo -u postgres psql -c "SHOW password_encryption;" # If you need to change it, edit postgresql.conf: # password_encryption = scram-sha-256 # Then reload (see step 6) and re-run the ALTER USER command from step 3.6. Reload PostgreSQL to apply pg_hba.conf and postgresql.conf changes
A reload is enough for pg_hba.conf and password_encryption changes. A full restart is not required. Warning: on a busy server, connections in progress will not be interrupted by a reload, but new connections will pick up the new config immediately.
# Ubuntu/Debian: sudo systemctl reload postgresql # RHEL / AlmaLinux / Rocky: sudo systemctl reload postgresql-16 # Replace 16 with your installed major version.7. Update the password in the application and confirm the connection
Update the DATABASE_URL, .env, or secrets manager entry with the new password, then test the connection from the application host rather than the database host.
psql "postgresql://your_user:new_password@127.0.0.1:5432/your_database"
Confirm it is fixed
Connect as the user from the same host and network path the application uses. A successful connection with no error confirms the fix. The '\conninfo' command shows which user and database you are connected to.
psql "postgresql://your_user:new_password@127.0.0.1:5432/your_database" -c "\conninfo"
# Good output looks like:
# You are connected to database "your_database" as user "your_user" via TCP/IP on "127.0.0.1" at port "5432".How Opservo catches it early
Opservo monitors PostgreSQL connection counts against max_connections and tracks sessions stuck idle in transaction, so a sudden spike in failed connection attempts that pushes active sessions toward the limit will surface as an alert before the pool is exhausted. If repeated authentication failures cause your application to open new connections faster than they close, Opservo will flag the rising connection count and give you plain-English context alongside the metric.
Last updated 2026-11-21.