Get Started Free

Fix "FATAL: password authentication failed for user"

Why PostgreSQL rejects your password: wrong or unset password, a missing user, a Docker volume with old credentials, or special characters in the URL.

Updated November 12, 2026 ยท Tested on PostgreSQL 16.14, psql 16, node-postgres 8.23, psycopg 3.3, psycopg2 2.9

Quick Answer

The server checked a password and it didn't match, or the user doesn't exist. Reset the password from a session that can still log in (usually as postgres over the local socket):

ALTER USER myuser WITH PASSWORD 'new-password';

Then reconnect with exactly that user and password. If you can't get any session at all, see "Locked out of every account" below.

What the error means

psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL:  password authentication failed for user "postgres"

The connection reached PostgreSQL, and the pg_hba.conf line that matched your connection asks for a password (scram-sha-256 or md5). The password check then failed. So the network, the port and the server are fine; the problem is the credentials or the role.

CauseHow to tell
Wrong passwordWorks with the right one; check for typos and stale env vars
The user does not exist\du doesn't list it. PostgreSQL deliberately reports this as a password failure.
The user has no password setrolpassword is NULL in pg_authid
The password expiredrolvaliduntil in pg_roles is in the past
Password stored as MD5, server expects SCRAMFails even with the right password; see below
Docker volume kept an old passwordYou changed POSTGRES_PASSWORD but reused the volume
Special characters in a connection URLPassword has @, :, / or #
Connecting to a different serverA local install and a container both on port 5432

In VisuaLeaf

Check the credentials in VisuaLeaf before your app does

When a connection string is involved, paste it into VisuaLeaf's PostgreSQL connection form, as a JDBC URL or a standard postgresql:// URL, and click Auto-Fill. The form splits it into host, port, database, username and password, so you can check each one. A password with an unencoded @, : or / that breaks the URL in the wrong place, the special-character problem described below, is easy to spot.

Then click Test Connection. It tries the settings without saving them, so you can change one field at a time until the server accepts it. If the server only accepts local logins, connect through an SSH tunnel instead of changing pg_hba.conf. Once it works, Export to URL turns the working settings back into a connection string for your app. See the Connection Manager.

VisuaLeaf PostgreSQL connection form filled from a pasted JDBC URL with Auto-Fill, showing host, port, database and credentials
Auto-Fill splits a pasted URL into fields you can check one by one.

Check the user exists and has a password

Connect however you still can and look at the role. A missing user produces this same message, not "role does not exist", so that nobody can probe which usernames are valid.

\du myuser
SELECT rolname, rolcanlogin, rolpassword IS NOT NULL AS has_password
FROM pg_authid WHERE rolname = 'myuser';   -- superuser only

Create it, or give it a password and login rights:

CREATE ROLE myuser WITH LOGIN PASSWORD 'new-password';
-- or, if it exists:
ALTER ROLE myuser WITH LOGIN PASSWORD 'new-password';

In psql, \password myuser prompts for the new password and sends it already hashed, so it doesn't end up in your shell history or the server log.

Docker: POSTGRES_PASSWORD is only read once

The official image sets the password from POSTGRES_PASSWORD only when it initializes an empty data directory. If a volume already holds a database, changing the variable does nothing and the old password stays.

# change the password inside the running container (local socket, no password needed)
docker exec -it my-postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'new-password';"

# or start over (deletes all data in the volume)
docker compose down -v && docker compose up -d

Also check you are hitting the container at all. If PostgreSQL is installed locally too, both may want port 5432, and your client connects to whichever won. Map the container to another port (-p 5433:5432) to remove the doubt.

Special characters in connection strings

In a URL, characters like @, :, /, ? and # have meaning, so a password containing them gets cut or misread. Percent-encode it:

# password: p@ss:w/rd
postgresql://app:p%40ss%3Aw%2Frd@localhost:5432/mydb
const url = `postgresql://app:${encodeURIComponent(process.env.DB_PASSWORD)}@localhost:5432/mydb`

Or skip the URL and pass the password as a separate option (password in node-postgres, password= in psycopg), which needs no escaping.

Locked out of every account

If no role can log in, temporarily let local connections in without a password, reset it, and change it back.

  1. Find the file: SHOW hba_file; from any session, or look in the data directory.
  2. Change the method on the local lines to trust: local all all trust.
  3. Reload: sudo systemctl reload postgresql or pg_ctl reload.
  4. Connect with psql -U postgres and run ALTER USER postgres WITH PASSWORD '...'.
  5. Put the original method back (scram-sha-256 or peer) and reload again.

Don't leave trust in place. It lets anyone who can reach that connection type log in as any user, superusers included.

What the server log says for each cause

The client gets the same one-line error for five different problems. We triggered each one on PostgreSQL 16.14 and read the server log (docker logs for a container, or the file in log_directory). The DETAIL line tells them apart:

What we didDETAIL line in the server log
Wrong passwordOnly Connection matched file ".../pg_hba.conf" line 128: "host all all all scram-sha-256". No reason given, which itself tells you the role exists and has a valid password.
User that doesn't existRole "learn_ghost" does not exist.
Role created without a passwordUser "learn_nopw" has no password assigned.
VALID UNTIL in the pastUser "learn_expired" has an expired password.
Right password, stored as MD5User "learn_md5" does not have a valid SCRAM secret.

The MD5 trap. A role whose password was set while password_encryption = 'md5' was in effect (common after upgrading from PostgreSQL 13 or older) can't log in through a scram-sha-256 line, even with the correct password. Check with SELECT rolname FROM pg_authid WHERE rolpassword LIKE 'md5%' and set those passwords again; they'll be stored as SCRAM. A md5 line in pg_hba.conf accepts both kinds.

Not every login failure is a password failure. A role without LOGIN gets its own message even over password auth, FATAL: role "x" is not permitted to log in, so if you see that, the password was never the problem. Fix it with ALTER ROLE x LOGIN.

The same failure in each client. All three connect to localhost, and on our machine localhost resolved to ::1 first, so the address in the message may be IPv6 even though you never typed one:

ClientWhat it reported
psqlconnection to server at "localhost" (::1), port 5432 failed: FATAL: password authentication failed for user "app"
node-postgreserror.code is 28P01, message password authentication failed for user "app"
psycopg 3Lists every address it tried: Multiple connection attempts failed. All failures were: - host: 'localhost', ... hostaddr: '::1' ... password authentication failed
psycopg2OperationalError: connection to server at "localhost" (::1), port 5432 failed: FATAL: password authentication failed for user "app"

If no password reaches the server at all, the errors are different: node-postgres throws SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a string (usually an unset environment variable), and libpq-based clients like psql and psycopg say fe_sendauth: no password supplied.

Frequently Asked Questions

What is the default password for the postgres user?

There isn't one. Package installs usually let the postgres OS user in via peer authentication with no password; the Docker image uses whatever POSTGRES_PASSWORD was set to on first start.

Why does it say password authentication failed when the user does not exist?

On purpose. Reporting unknown users separately would let an attacker discover valid usernames, so PostgreSQL gives the same error for both. The server log has the real reason.

Where can I see the real reason for the failure?

In the PostgreSQL server log. It adds a DETAIL line such as Role "x" does not exist or User "x" has no password assigned, plus the pg_hba.conf line that matched.

Why does the right password still fail after a PostgreSQL upgrade?

The password is probably still stored as an MD5 hash while pg_hba.conf now requires scram-sha-256. The server log says the user does not have a valid SCRAM secret. Set the password again to store it as SCRAM.

Do I need to restart after changing a password?

No. ALTER USER takes effect immediately for new connections. Changes to pg_hba.conf need a reload, not a restart.

VisuaLeaf

Test PostgreSQL credentials before you save them

VisuaLeaf's connection manager tests a connection as you set it up, keeps credentials for every server in one place, and connects through SSH tunnels when the database isn't reachable directly.