Cloud Explainers

How to Fix PostgreSQL 'Password Authentication Failed'

PostgreSQL7 min videoPublished Nov 16, 2026

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

Ana at the office PC
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"
Ana at the office PC
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.

How PostgreSQL checks a login: diagram of Office PC, pg_hba.conf, scram-sha-256, Lessons server, Server 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.

What the client sees vs what the log says: comparison table of At the door vs At the front desk, Hotel, PostgreSQL, Why, So the fix

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.

Ana on the lessons server
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.

Ana: lessons server and office PC
sudo -u postgres psql -c '\password booking'Enter new password for user "booking":
Enter it again:
Ana: lessons server and office PC
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.

Ana: lessons server and office PC
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"
Ana: lessons server and office PC
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.

One letter: the user name: code change of ~/school/booking.env, DATABASE_URL=postgresql://booking:Minor-Key-7@lessons/school (user booking, as created), postgresql://user:password@host/database

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.

Ana on the lessons server
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.

Ana on the lessons server
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
Ana on the lessons server
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.

Ana: lessons server and office PC
sudo -u postgres createuser ben
Ana: lessons server and office PC
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"
Ana: lessons server and office PC
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"
Ana: lessons server and office PC
sudo -u postgres psql -c '\password ben'Enter new password for user "ben":
Enter it again:
Ana: lessons server and office PC
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.

Ana: lessons server and office PC
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"
Ana: lessons server and office PC
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"
Ana: lessons server and office PC
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.

The right password, still refused: browser screenshot from the video

So Ana sets piano's password again, the very same one. Now it's stored as SCRAM, and piano logs in.

Ana: lessons server and office PC
sudo -u postgres psql -c '\password piano'Enter new password for user "piano":
Enter it again:
Ana: lessons server and office PC
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)
Ana: lessons server and office PC
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.

Ana at the office PC
grep PASSWORD compose.yaml      POSTGRES_PASSWORD: Tuning-Fork-440
Ana at the office PC
docker compose up -d Container testdb-db-1  Recreate
 Container testdb-db-1  Recreated
 Container testdb-db-1  Starting
 Container testdb-db-1  Started
Ana at the office PC
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.

Ana at the office PC
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.

Ana at the office PC
docker compose exec db psql -U postgres -c '\password'Enter new password for user "postgres":
Enter it again:
Ana at the office PC
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.

Before you call it fixed: cards of Test the app's exact login, After a move: look for md5

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.

What the log's detail line means: diagram of Only "Connection matched", Role "x" does not exist, has no password assigned, no valid SCRAM secret

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

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.

More videos

DevOps & CI/CD9 min

DevOps with Ansible Will Finally Make Sense After This

Networking9 min

How SNMP Network Monitoring Works

Git8 min

How to Fix GitHub 'Permission Denied (publickey)' Errors

Linux8 min

Why One Linux Server Handles More Users Than You Think

Networking7 min

How to Fix Network 'Connection Refused' Errors

DevOps & CI/CD9 min

DevOps Pipelines: Jenkins vs GitHub Actions

Networking11 min

Every Networking Term a Beginner Needs in 12 Minutes

Docker6 min

How to Fix Docker 'Permission Denied' on docker.sock

Git7 min

How to Fix Git 'Updates Were Rejected' When You Push

Linux7 min

How to Fix nginx 502 Bad Gateway Errors on Linux

Linux8 min

How to Fix Linux apt 'Could Not Get Lock' Errors (Ubuntu)

Networking9 min

How Email Works on the Internet (SMTP) in 10 Minutes

Python8 min

The Python Roadmap for Beginners

Go (Golang)21 min

Golang REST API with Gin: Full Tutorial for Beginners

Networking10 min

How a WireGuard VPN Network Works

Linux9 min

Linux Makefiles Will Finally Make Sense After This

Auth (OAuth, JWT)9 min

SAML vs OAuth vs OpenID Connect: What's the Difference?

Python7 min

How to Fix Python cron Jobs That Never Run

Linux22 min

Linux Bash Scripting: Full Tutorial for Beginners

Networking10 min

How PXE Network Boot Works

Active Directory9 min

How Active Directory Works

Linux10 min

How to Fix a Linux systemd Service That Won't Start

Linux9 min

Linux Logs: syslog vs journald

Auth (OAuth, JWT)9 min

JWT vs Session Cookies: Which One Should You Use?

Docker10 min

Docker vs Docker Compose: Which One Should You Use?

Docker9 min

How to Fix Docker Compose Containers That Can't Talk to Each Other

Django (Python web framework)22 min

Django Full Tutorial for Beginners

Linux9 min

How Linux systemd Works

Networking8 min

How to Fix 'Windows Cannot Access' Network Share Errors (SMB)

APIs10 min

REST vs gRPC: Which One Should You Use?

Certificates & PKI (ADCS)9 min

How to Fix SSL Certificate Chain Errors (Missing Intermediate)

Python9 min

Every Python Concept for Beginners in 10 Minutes

Databases & SQL9 min

Every SQL Join Type in 10 Minutes

OpenRouter (one API for many AI models)9 min

Why OpenRouter Free Models Hit Their Limit So Fast

Gemini API & Google AI Studio9 min

Why Your Gemini API Free Tier Runs Out So Fast

OpenRouter (one API for many AI models)10 min

OpenRouter Will Finally Make Sense After This

Caching & Redis10 min

How Redis Caching Works

Gemini API & Google AI Studio10 min

Gemini API vs Vertex AI: Which One Should You Use?

Gemini API & Google AI Studio8 min

How to Fix a Leaked Gemini API Key

Go (Golang)9 min

Why Golang Uses Goroutines Instead of Threads

Gemini API & Google AI Studio9 min

How to Fix Gemini API Error 429: Resource Exhausted

Claude & the Claude Developer Platform10 min

Claude Token Pricing Will Finally Make Sense After This

Python11 min

Why Python Web Scraping Returns Nothing (and the Fix)

Python10 min

Python uv vs pip: Which One Should You Use?

Python22 min

Python Automation: Full Tutorial for Beginners

Auth (OAuth, JWT)9 min

How OAuth Login Works

Gemini API & Google AI Studio10 min

Google AI Studio Will Finally Make Sense After This

Docker10 min

What Happens When You Run a Docker Container

Claude & the Claude Developer Platform8 min

How to Fix Claude Code Billing Your API Key Instead of Your Plan

Auth (OAuth, JWT)9 min

Why Passkeys Can't Be Phished Like Passwords

PowerShell10 min

PowerShell vs Bash: Which One Should You Learn?

Linux10 min

The Linux Roadmap for Beginners

Django (Python web framework)9 min

Django vs FastAPI: Which One Should You Use?

Databases & SQL10 min

Why SQLite Is the Most Used Database in the World

Databases & SQL11 min

How a NoSQL Database Like MongoDB Works

Python11 min

How to Fix Python pip error: externally-managed-environment

Databases & SQL9 min

How to Fix MySQL Too Many Connections Database Errors

Go (Golang)9 min

Golang Concurrency Will Finally Make Sense After This

AWS10 min

How Amazon S3 Works

Kubernetes10 min

How Kubernetes Works

Git10 min

How Git Works

Docker10 min

How to Fix Docker Port Already Allocated Errors

PostgreSQL10 min

How PostgreSQL Works

Git8 min

How to Fix Git Merge Conflicts

Linux9 min

How to Fix No Space Left on Device in Linux

Networking10 min

How the Internet Works

Databases & SQL9 min

SQL vs NoSQL: When Each One Wins

Auth (OAuth, JWT)8 min

How to Fix JWT Token Expired Errors (401 Unauthorized)

Claude & the Claude Developer Platform9 min

Claude API vs Claude Pro: Why Your Subscription Doesn't Include It

AI agent skills9 min

Why AI Agent Skills Beat Giant Prompts

Linux10 min

Linux Cron Jobs Will Finally Make Sense After This

Cybersecurity10 min

Security Logs Will Finally Make Sense After This

Cybersecurity8 min

How to Fix a Security Leak: An API Key Pushed to GitHub

DNS9 min

DNS Will Finally Make Sense After This

Cybersecurity9 min

Never Ignore a Security Update

Auth (OAuth, JWT)9 min

Two-Factor Authentication Will Finally Make Sense

Networking8 min

Never Expose a Database to the Internet

Cybersecurity10 min

SSH Keys vs Passwords: Which Is Safer for Security?

Linux10 min

The 5 Levels of Linux Boot: From Power On to Login

Networking12 min

The 5 Levels of Network Firewalls

Cybersecurity10 min

Password Security: Why Hackers Crack Weak Passwords

Linux9 min

Why Your Linux Server Runs Out of Memory

Networking10 min

HTTP vs HTTPS: What Actually Changes on Your Network

Linux12 min

Every Linux File Permission You Need to Know

Linux10 min

Linux Processes vs Threads: When Each One Wins

Networking11 min

The OSI Model Will Finally Make Sense After This

Git11 min

The 7 Levels of Git

Networking10 min

Every Network Troubleshooting Command You Need

Cybersecurity10 min

Hashing vs Encryption in Cybersecurity: When Each One Wins

Networking11 min

Why the Internet Ran Out of IP Addresses

Linux11 min

Linux Package Managers: apt vs Snap vs Flatpak

Python9 min

Why Python Is Slow (and When It Doesn't Matter)

Networking11 min

TCP vs UDP: When Each One Wins

Linux8 min

Stop Running Linux as Root (Do This Instead)

Linux11 min

Linux Users and Groups Will Finally Make Sense

Cybersecurity9 min

Why Phishing Beats Good Security (and How to Spot It)

Docker12 min

The 7 Levels of Docker

AI agents & MCP12 min

AI Agents Will Finally Make Sense After This

Git8 min

Stop Using git push --force (Use This Instead)

AI agent skills10 min

Agent Skills vs MCP: When Each One Wins

Networking12 min

Networking Will Finally Make Sense After This

Linux12 min

Every Linux Command You Actually Need

Cybersecurity12 min

The 7 Levels of Cybersecurity

System design12 min

Every System Design Concept You Need, in One Diagram

PostgreSQL10 min

Why PostgreSQL Ignores Your Index