How to Fix PostgreSQL 'Password Authentication Failed'
'FATAL: password authentication failed for user' is the same sentence for a wrong password, a user that doesn't exist, a user with no password and a password stored as an old md5 hash. On a real Ubuntu 24.04 server with PostgreSQL 16.15 we read the server's log, which names the real reason, and fix each one, plus peer authentication on the server itself and the Docker image that ignores a new POSTGRES_PASSWORD.
Refused, and it won't say why
Your app says: password authentication failed. At a music school's office, Ana's booking screen asks the school's database for today's lessons, and gets a fatal error: password authentication failed for user booking. psql, PostgreSQL's own client, says the same: dash h for the server, dash U for the user, then the database, and the password from the app's settings. PostgreSQL knows exactly what went wrong. It just isn't telling you. And one cause on the way fails even with the right password.
python3 book.pyTraceback (most recent call last): File "/home/ana/school/book.py", line 10, in <module> conn = psycopg2.connect(env["DATABASE_URL"]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/usr/lib/python3/dist-packages/psycopg2/__init__.py", line 122, in connect conn = _connect(dsn, connection_factory=connection_factory, **kwasync) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ psycopg2.OperationalError: connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "booking" connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "booking"
psql -h lessons -U booking schoolPassword for user booking: psql: error: connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "booking" connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "booking"
How PostgreSQL checks a login
How does PostgreSQL check a login? First it reads pg_hba.conf, a list of rules, top to bottom. The first line that matches the connection, the database, the user and the address wins. For the office, that line says scram: prove you know the password. If anything goes wrong, the client gets one sentence, and the real reason goes into the server's log.

It's like a hotel key card. The door's light turns red whether the card is wrong, expired, or for another room. The front desk's system knows which. It's the same sentence on purpose: telling a stranger which user names exist would help them guess. So the fix always starts at the front desk: the server's log.

The reason is in the server's log
So the usual fix first: like at the hotel, go to the front desk: the log. In a second window, logged in on the lessons server, sudo tail shows its last lines. The same failure, then a detail line: which pg_hba.conf line matched, line one thirty-five. And no other reason. The user exists and has a password, so the password itself didn't match. The app still has the old one; the server's was changed last week.
sudo tail -n 2 /var/log/postgresql/postgresql-16-main.log2026-11-16 13:38:48.885 UTC [178] booking@school FATAL: password authentication failed for user "booking" 2026-11-16 13:38:48.885 UTC [178] booking@school DETAIL: Connection matched file "/etc/postgresql/16/main/pg_hba.conf" line 135: "host all all 192.168.70.0/24 scram-sha-256"
Backslash password, run with sudo as postgres, the administrator account, sets a new password. It asks twice and never shows it, so it doesn't land in your shell history. Ana types the one the app already uses, and the booking screen shows Monday's three lessons.
sudo -u postgres psql -c '\password booking'Enter new password for user "booking": Enter it again:
python3 book.py15:30:00 room 2 Leo (piano) 16:15:00 room 1 Mia (violin) 17:00:00 room 2 Sam (guitar)
Wrong user, same message
The next morning, the same sentence again. Look closely at the user: bookings, with an s. The log says it plainly: role bookings does not exist; role is PostgreSQL's word for a user. A user that isn't there gets the same message as a wrong password.
python3 book.pyTraceback (most recent call last): File "/home/ana/school/book.py", line 10, in <module> conn = psycopg2.connect(env["DATABASE_URL"]) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/usr/lib/python3/dist-packages/psycopg2/__init__.py", line 122, in connect conn = _connect(dsn, connection_factory=connection_factory, **kwasync) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ psycopg2.OperationalError: connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "bookings" connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "bookings"
sudo tail -n 3 /var/log/postgresql/postgresql-16-main.log2026-11-16 13:38:49.939 UTC [188] bookings@school FATAL: password authentication failed for user "bookings" 2026-11-16 13:38:49.939 UTC [188] bookings@school DETAIL: Role "bookings" does not exist. Connection matched file "/etc/postgresql/16/main/pg_hba.conf" line 135: "host all all 192.168.70.0/24 scram-sha-256"
A colleague had edited the app's settings file. One letter in the address, the user name before the colon. Take the s off, and the booking screen works again.

On the server itself: peer
On the lessons server itself, Ana runs psql as the same booking user. Guess first: does it ask for the password? No. A different message: peer authentication failed, and no password question at all.
psql -U booking schoolpsql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: Peer authentication failed for user "booking"
pg_hba.conf explains it: grep, without the comment lines, shows its rules. Without a host name, psql uses a local socket, a file on the server, and that matches a local line: peer. Peer asks Linux who you are, and Linux says ana, not booking. Dash h localhost makes it a network connection, so the same login takes a host line, scram, the password, and the three lessons.
sudo grep -v '^#' /etc/postgresql/16/main/pg_hba.conf | grep .local all postgres peer local all all peer host all all 127.0.0.1/32 scram-sha-256 host all all ::1/128 scram-sha-256 local replication all peer host replication all 127.0.0.1/32 scram-sha-256 host replication all ::1/128 scram-sha-256 host all all 192.168.70.0/24 scram-sha-256
psql -h localhost -U booking school -c 'SELECT count(*) FROM lessons'Password for user booking: count ------- 3 (1 row)
A user with no password
A new teacher, Ben, gets an account with createuser. From the office, every password fails. The log: user ben has no password assigned. createuser makes a user with no password unless you ask for one, and so does a fresh install for postgres, the administrator. Backslash password ben, and Ben is in.
sudo -u postgres createuser ben
psql -h lessons -U ben schoolPassword for user ben: psql: error: connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "ben" connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "ben"
sudo tail -n 3 /var/log/postgresql/postgresql-16-main.log2026-11-16 13:38:50.917 UTC [208] ben@school FATAL: password authentication failed for user "ben" 2026-11-16 13:38:50.917 UTC [208] ben@school DETAIL: User "ben" has no password assigned. Connection matched file "/etc/postgresql/16/main/pg_hba.conf" line 135: "host all all 192.168.70.0/24 scram-sha-256"
sudo -u postgres psql -c '\password ben'Enter new password for user "ben": Enter it again:
psql -h lessons -U ben school -c 'SELECT current_user'Password for user ben: current_user -------------- ben (1 row)
The right password, still refused
Now the one that fails with the right password. Piano is an account copied over from the school's old server. Ana types its password, letter for letter, and it's refused. The log: user piano does not have a valid SCRAM secret. The server never keeps a password, only a hash of it, a fingerprint to check it against. pg_authid, PostgreSQL's own table of users, shows them: booking's hash is SCRAM, but piano's hash is an old md5 one, which a scram line can't check.
psql -h lessons -U piano schoolPassword for user piano: psql: error: connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "piano" connection to server at "lessons" (192.168.70.10), port 5432 failed: FATAL: password authentication failed for user "piano"
sudo tail -n 3 /var/log/postgresql/postgresql-16-main.log2026-11-16 13:38:52.665 UTC [220] piano@school FATAL: password authentication failed for user "piano" 2026-11-16 13:38:52.665 UTC [220] piano@school DETAIL: User "piano" does not have a valid SCRAM secret. Connection matched file "/etc/postgresql/16/main/pg_hba.conf" line 135: "host all all 192.168.70.0/24 scram-sha-256"
sudo -u postgres psql -c "SELECT rolname, left(rolpassword, 14) AS stored FROM pg_authid WHERE rolname IN ('booking', 'piano')"rolname | stored ---------+---------------- piano | md5f9f78dc43e9 booking | SCRAM-SHA-256$ (2 rows)
PostgreSQL's own guide says what to do after a move like this: switch to scram, and make all users set new passwords.

So Ana sets piano's password again, the very same one. Now it's stored as SCRAM, and piano logs in.
sudo -u postgres psql -c '\password piano'Enter new password for user "piano": Enter it again:
sudo -u postgres psql -c "SELECT rolname, left(rolpassword, 14) AS stored FROM pg_authid WHERE rolname IN ('booking', 'piano')"rolname | stored ---------+---------------- booking | SCRAM-SHA-256$ piano | SCRAM-SHA-256$ (2 rows)
psql -h lessons -U piano school -c 'SELECT current_user'Password for user piano: current_user -------------- piano (1 row)
PostgreSQL in Docker
One more, if you run PostgreSQL in Docker. Ana's test copy on the office PC started a month ago. Today she puts a new password in compose dot yaml, and Compose recreates the container. Guess first: which password works now? The old one. The new one is refused.
grep PASSWORD compose.yamlPOSTGRES_PASSWORD: Tuning-Fork-440
docker compose up -dContainer testdb-db-1 Recreate Container testdb-db-1 Recreated Container testdb-db-1 Starting Container testdb-db-1 Started
psql -h localhost -U postgresPassword for user postgres: psql: error: connection to server at "localhost" (::1), port 5432 failed: FATAL: password authentication failed for user "postgres"
The container's own log says why: the database directory already contains a database, skipping initialization. The image reads that password only once, when its data folder is empty. The data lives in a volume, storage that outlives the container, so the old password stayed with it.
docker compose logs db | grep -i skippingdb-1 | PostgreSQL Database directory appears to contain a database; Skipping initialization
So set it inside the database, as before. docker compose exec runs psql in the container, where the image trusts local connections without a password, and backslash password changes it. The new password works. Deleting the volume, with docker compose down dash v, works too, but it deletes every row with it.
docker compose exec db psql -U postgres -c '\password'Enter new password for user "postgres": Enter it again:
psql -h localhost -U postgres -c 'SELECT current_user'Password for user postgres: current_user -------------- postgres (1 row)
Before you call it fixed
Before you call it fixed, test the exact login your app uses: same user, same host, same database, from the same machine. And after moving to a new server, check pg_authid for old md5 hashes, before your users find them.

Recap
So: one sentence for the client, the reason in the log. No reason: a wrong password. Role does not exist: a wrong user. No password assigned: set one. No valid SCRAM secret: set it again.

If your app can log in again, subscribing brings more fixes, tested on real servers.
Every failure in this video came from a real PostgreSQL server, and every command and the lab files are linked in the description. Thanks for watching Cloud Explainers.
Sources
- PostgreSQL 16, The pg_hba.conf File (the first matching line is used; local = Unix socket, host = TCP/IP)
- PostgreSQL 16, Password Authentication (scram-sha-256 and md5 hashes, pg_authid, upgrading from md5)
- PostgreSQL 16, Peer Authentication (the operating system user name must match)
- PostgreSQL 16, psql \password (asks for the new password, never shows it)
- PostgreSQL 16, createuser (-P asks for a password; without it the user has none)
- PostgreSQL 16, libpq SSL support (sslmode prefer: try SSL first, then without)
- The postgres Docker image (POSTGRES_PASSWORD only takes effect with an empty data directory)
Demos: two containers on our own Mac standing in for a music school's office PC and database server; the school, its staff and its passwords are made up. Every failure and log line was real. Watch the full video on YouTube.