PostgreSQL password authentication failures occur when credentials are incorrect, misconfigured, or the authentication method is incompatible. Verify your password, connection string, and pg_hba.conf settings to resolve.
PostgreSQL's "Invalid password" error (SQLSTATE 28P01) occurs during the authentication phase when a client attempts to connect with incorrect credentials or when the authentication method doesn't match the server configuration. This is distinct from other authorization failures—it specifically means the password provided doesn't match the stored password hash, or the authentication mechanism itself failed. The error can also occur if the user account exists but has no password set, or if the connection string is malformed due to special characters in the password.
Double-check that you're using the exact password set when the user account was created. PostgreSQL passwords are case-sensitive.
Try connecting with psql directly:
psql -U postgres -h localhost -d postgresIf prompted, enter your password carefully. If this works, the issue may be with how your application passes the password.
If your password contains special characters (@, :, %, $, #, etc.), they must be percent-encoded in connection URLs.
For example, if your password is my@pass:123, encode it as my%40pass%3A123:
# Wrong - @ and : will break the URL parsing
psql "postgresql://user:my@pass:123@localhost:5432/mydb"
# Correct - special characters encoded
psql "postgresql://user:my%40pass%3A123@localhost:5432/mydb"Or use the connection parameters approach instead:
psql -h localhost -U user -d mydb -WThis prompts for password without URL parsing issues.
If the user was created without a password, you'll get an authentication failure. Connect as a superuser and set the password:
sudo su - postgres
psqlThen set or reset the password:
ALTER ROLE username WITH PASSWORD 'new_password';
ALTER ROLE username LOGIN;
\qTest the connection:
psql -U username -h localhost -d postgres -WPostgreSQL uses pg_hba.conf to determine how clients authenticate. If it's set to peer or ident, password authentication is bypassed.
Locate pg_hba.conf (usually in /etc/postgresql/{version}/main/ on Linux or %AppData%\PostgreSQL\{version}\pg_hba.conf on Windows):
sudo cat /etc/postgresql/15/main/pg_hba.conf | grep -v "^#"Look for lines like:
# TYPE DATABASE USER ADDRESS METHOD
local all all peer
host all all 127.0.0.1/32 md5
host all all ::1/128 md5If you see peer for local connections, change to md5 or scram-sha-256:
local all all scram-sha-256Save the file and restart PostgreSQL:
sudo systemctl restart postgresqlPostgreSQL 10+ defaults to SCRAM-SHA-256, but older clients may only support MD5. Check your client library version.
If using Docker, DBeaver, or pgAdmin, ensure they're updated:
# Python
pip install --upgrade psycopg2-binary
# Node.js
npm install --upgrade pg
# Ruby
gem update pgIf you must support legacy clients, modify pg_hba.conf to use MD5 (less secure):
host all all 127.0.0.1/32 md5Then restart PostgreSQL.
After any pg_hba.conf changes, PostgreSQL must be restarted for changes to take effect.
On Linux (systemd):
sudo systemctl restart postgresqlOn Linux (older systems):
sudo service postgresql restartOn macOS (Homebrew):
brew services restart postgresqlOn Windows (Services):
1. Press Win+R, type services.msc
2. Find "postgresql-x64-{version}" and right-click → Restart
Verify it's running:
sudo systemctl status postgresqlSCRAM-SHA-256 vs MD5: PostgreSQL 10+ uses SCRAM-SHA-256 by default (more secure). If your application or tool doesn't support SCRAM, you must either upgrade the client library or downgrade the server authentication method in pg_hba.conf. Cloud PostgreSQL (RDS, Azure, Heroku) may enforce SCRAM or specific authentication methods—check your provider's documentation.
Docker Gotchas: When using Docker, password authentication often fails because the POSTGRES_PASSWORD environment variable isn't being read correctly, or pg_hba.conf defaults to peer. Set POSTGRES_PASSWORD and use -e flags, and consider overriding pg_hba.conf with a custom configuration file.
Connection Poolers (PgBouncer, Pgpool): These tools have their own authentication layer (pool_passwd file). Password failures here require checking pool_passwd for the user, not just the PostgreSQL database.
URL Encoding Edge Case: If you encode the password in your application, verify you're not double-encoding (encoding an already-encoded string). Test with plain psql first to isolate the issue.
insufficient columns in unique constraint for partition key
How to fix "insufficient columns in unique constraint for partition key" in PostgreSQL
ERROR 42501: must be owner of table
How to fix "must be owner of table" in PostgreSQL
trigger cannot change partition destination
How to fix "Trigger cannot change partition destination" in PostgreSQL
SSL error: certificate does not match host name
SSL error: certificate does not match host name in PostgreSQL
No SSL connection
No SSL connection to PostgreSQL