5 Ways to Fix PostgreSQL password authentication failed for user postgres

5 Ways to Fix PostgreSQL password authentication failed for user postgres

psql: error: FATAL:  password authentication failed for user "postgres"

You've probably seen this one-liner and retyped the password about ten times. Surprisingly, the real problem is often not the password. This error collapses five causes across four areas—credentials, account state, authentication method, and network—into the same message. That's why blindly changing the password doesn't fix it.

This post walks through diagnosing and isolating the issue from the top down, with copy-paste commands, so you don't panic.

Start with the diagnostic order — top to bottom

When the error hits, follow this order as-is. If an earlier step catches it, skip the rest.

Causes 1, 3, and 4 — credentials and the account itself

Cause 1: Typos and missing environment variables

This is the most common—and most anticlimactic—cause. If an environment variable never gets injected and you try to connect with an empty string, PostgreSQL just reports authentication failed. Check it directly in the shell.

echo "[$DB_PASSWORD]"   # 대괄호 사이가 비었다면 변수 주입 실패
psql -U postgres -h localhost -d postgres

If the password contains special characters like ! or $, the shell will mangle them, so always manage variables with single quotes or a .env file.

Cause 3: User or database does not exist

The role or database you're connecting to might not actually exist. Connect as a superuser and check the lists first.

\du           -- 롤(사용자) 목록과 권한
\l            -- 데이터베이스 목록

If postgres is missing from \du, the account itself is the problem—before authentication even starts.

Cause 4: Password is unset or does not match

With source builds or some install methods, the postgres role may have no password at all. Connect as a superuser and reset it.

ALTER ROLE postgres WITH PASSWORD 'newpass';

If you want to see the stored hash format, run the following. The output is prefixed with SCRAM-SHA-256$ or md5.

SELECT rolname, rolpassword FROM pg_authid WHERE rolname = 'postgres';

Cause 2 — pg_hba.conf authentication method mismatch

This is the trap that has bitten the most people since PostgreSQL 14. pg_hba.conf defines which authentication method to use for which connection. If the way the server stored the password doesn't match the method it says it will accept, authentication fails even when the password is correct.

First, find the file location.

SHOW hba_file;
SHOW password_encryption;   -- scram-sha-256 또는 md5

scram vs md5 — why they get out of sync

Here's the key point. Starting with PostgreSQL 14, the default for password_encryption changed from md5 to scram-sha-256. So if you migrated from an older version, or pg_hba.conf still says md5 while the password is stored as scram, they collide.

Align pg_hba.conf like this.

# TYPE  DATABASE  USER  ADDRESS       METHOD
# 변경 전
local   all       all                 md5
host    all       all   127.0.0.1/32  md5
# 변경 후 (권장)
local   all       all                 scram-sha-256
host    all       all   127.0.0.1/32  scram-sha-256

After editing, reload without a restart.

SELECT pg_reload_conf();

pg_ctl reload   # 또는 sudo systemctl reload postgresql

Practical tip: If it still fails after switching the method to scram, the password is likely still stored as an md5 hash. Resetting it once more with ALTER ROLE ... PASSWORD rehashes it using the current password_encryption setting. On production DBs I upgraded to 14, that one line closed more than half of the auth tickets.

Cause 5 — Docker, remote connections, and Spring config

If it works locally but fails only from Docker or a remote host, it's more likely a network exposure problem than authentication.

Open the listen address in postgresql.conf and add an external host line in pg_hba.conf.

# postgresql.conf
listen_addresses = '*'

# pg_hba.conf
host  all  all  0.0.0.0/0  scram-sha-256

When you start it with Docker, you must set the password via an environment variable so the postgres role is created with that value.

docker run -d --name pg \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_USER=postgres \
  -p 5432:5432 postgres:16

Check Spring application.yml

The most common Spring Boot mistake is the app still trying to connect with an empty password when the environment variable was never injected.

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: postgres
    password: ${DB_PASSWORD}   # 미주입 시 빈 문자열 → 인증 실패
    driver-class-name: org.postgresql.Driver

Older JDBC drivers also don't support scram authentication. Upgrade the driver to the latest 42.x, and in some environments check that the scram dependency (com.ongres.scram) is included. Recent org.postgresql:postgresql:42.x usually bundles it automatically.

Wrap-up: diagnostic checklist and recommended settings

1. echo $DB_PASSWORD     → 오타·빈 문자열 확인
2. \du / \l              → 계정·DB 존재 확인
3. ALTER ROLE ... PASSWORD → 비밀번호 재설정(해시 갱신)
4. SHOW hba_file → method를 scram으로 통일 → reload
5. listen_addresses='*', host 0.0.0.0/0 → 네트워크 확인

Isolate from the top down and most cases resolve within the first three steps. In production, standardize on scram-sha-256 instead of md5, and narrow 0.0.0.0/0 to a trusted CIDR whenever you can.

References: official docs

The primary source for the behavior, settings, and errors covered here is the official documentation. Check version-specific options and exact behavior there.

• PostgreSQL official documentation

FAQ

Q. The password is definitely correct, but it still fails. Why? A. The authentication method in pg_hba.conf is likely out of sync with the stored hash format. Set the method to scram-sha-256, reset the password with ALTER ROLE postgres WITH PASSWORD '...' so the hash is rewritten in the new format, then run pg_reload_conf().

Q. It connects locally but fails only from Docker or a remote host. A. It may be an exposure setting, not authentication. Set listen_addresses = '*' and add a host all all 0.0.0.0/0 scram-sha-256 line in pg_hba.conf, then reload.

Q. After upgrading to PostgreSQL 14, only the Spring app gets an auth error. A. Starting with 14 the default auth is scram-sha-256, and older JDBC drivers can't handle it. Upgrade the org.postgresql:postgresql driver to the latest 42.x.