How to fix Invalid password in PostgreSQL

PostgreSQLINTERMEDIATEHIGHUpdated Dec 26, 2025· 1,201 views

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.

Quick fix

Fixes 28P01

psql -U postgres -h localhost -d postgres
  1. Verify the password is correct
  2. Check for special characters in your password
  3. Ensure the user has a password set
  4. Check pg_hba.conf authentication method
postgresql — error
psql -U postgres -h localhost -d postgres
Invalid password

What this error means

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.

Typical symptoms

  • psql: error: connection to server... FATAL: password authentication failed for user
  • Database clients (DBeaver, pgAdmin, psycopg2) fail to connect with "Invalid password" message
  • Newly created PostgreSQL instances reject the default password
  • Connection works with one client tool but fails with another (SCRAM vs MD5 mismatch)
  • Application connection strings work on one server but fail after upgrade to PostgreSQL 10+
  • Connection fails only over remote/network connections, not local socket connections

Common causes

  1. Password is incorrect or typo in credentials
  2. Special characters in password not URL-encoded in connection string (@, :, %, $, etc.)
  3. User account created without password (CREATE USER without PASSWORD clause)
  4. pg_hba.conf configured to use peer or ident authentication instead of md5/scram-sha-256
  5. PostgreSQL upgrade changed default authentication method (PostgreSQL 13.3+ uses SCRAM-SHA-256)
  6. Double-encoding of special characters in password strings
  7. Connection string points to wrong host, port, or database name
  8. PostgreSQL service not restarted after pg_hba.conf changes
  9. Case sensitivity mismatch (MyPass ≠ mypass) if password was set case-sensitively

How to fix "Invalid password"

1Verify the password is correct

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:

bash
psql -U postgres -h localhost -d postgres

If prompted, enter your password carefully. If this works, the issue may be with how your application passes the password.

2Check for special characters in your 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:

bash
# 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:

bash
psql -h localhost -U user -d mydb -W

This prompts for password without URL parsing issues.

3Ensure the user has a password set

If the user was created without a password, you'll get an authentication failure. Connect as a superuser and set the password:

bash
sudo su - postgres
psql

Then set or reset the password:

sql
ALTER ROLE username WITH PASSWORD 'new_password';
ALTER ROLE username LOGIN;
\q

Test the connection:

bash
psql -U username -h localhost -d postgres -W
4Check pg_hba.conf authentication method

PostgreSQL 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):

bash
sudo cat /etc/postgresql/15/main/pg_hba.conf | grep -v "^#"

Look for lines like:

bash
# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             all                                     peer
host    all             all             127.0.0.1/32            md5
host    all             all             ::1/128                 md5

If you see peer for local connections, change to md5 or scram-sha-256:

bash
local   all             all                                     scram-sha-256

Save the file and restart PostgreSQL:

bash
sudo systemctl restart postgresql
5Verify authentication method compatibility

PostgreSQL 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:

bash
# Python
pip install --upgrade psycopg2-binary

# Node.js
npm install --upgrade pg

# Ruby
gem update pg

If you must support legacy clients, modify pg_hba.conf to use MD5 (less secure):

bash
host    all             all             127.0.0.1/32            md5

Then restart PostgreSQL.

6Confirm PostgreSQL service restarted

After any pg_hba.conf changes, PostgreSQL must be restarted for changes to take effect.

On Linux (systemd):

bash
sudo systemctl restart postgresql

On Linux (older systems):

bash
sudo service postgresql restart

On macOS (Homebrew):

bash
brew services restart postgresql

On Windows (Services):
1. Press Win+R, type services.msc
2. Find "postgresql-x64-{version}" and right-click → Restart

Verify it's running:

bash
sudo systemctl status postgresql

Advanced notes

SCRAM-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.

Frequently asked questions

What does "28P01" mean?
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.
How do I fix "28P01"?
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.
What causes "28P01"?
Password is incorrect or typo in credentials Special characters in password not URL-encoded in connection string (@, :, %, $, etc.) User account created without password (CREATE USER without PASSWORD clause)
Is the "28P01" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading