DEV Community: Milind Satpute

🚀 Fixing PgBouncer “FATAL: server login failed: wrong password type” When Using PostgreSQL 15–18+

Milind Satpute — Tue, 09 Dec 2025 19:13:26 +0000

If you're using PgBouncer as a connection pooler in front of PostgreSQL 15+ (including 18+), you may hit this frustrating error in your logs or in your client apps (DBeaver, psql, applications):

FATAL: server login failed: wrong password type

This issue usually appears after upgrading PostgreSQL or when deploying PgBouncer in Docker with the default configuration.

The good news?
It’s not actually a bug — it’s a password hash mismatch.

Let’s walk through the root cause and the cleanest fix.

❗ Why this error happens

PostgreSQL 14 and later default to SCRAM-SHA-256 passwords:

SHOW password_encryption; 
-- scram-sha-256

Meanwhile, PgBouncer traditionally expected MD5 hashes in its userlist.txt.

When PgBouncer reads an MD5 hash but the actual PostgreSQL user is stored as SCRAM, authentication fails with:

wrong password type

This happens because PgBouncer tries to forward the MD5-based password to PostgreSQL, but PostgreSQL rejects it — the hash formats don’t match.

🔍 Signs you are affected

PgBouncer logs show:

  FATAL: server login failed: wrong password type

DBeaver or your app says:

  password authentication failed

You are running:
- PostgreSQL 14, 15, 16, 17, or 18+
- Any Dockerized PgBouncer setup (edoburu, bitnami, cloudnative-pg, icoretech, etc.)

✅ The Correct Fix: Use SCRAM hashes inside PgBouncer’s `userlist.txt`

PgBouncer can authenticate using SCRAM — you just have to give it the actual SCRAM hashes from PostgreSQL.

Step 1 — Get the SCRAM hash from PostgreSQL

Run as a superuser:

SELECT rolpassword 
FROM pg_authid 
WHERE rolname = 'myappuser';

This returns something like:

SCRAM-SHA-256$4096:kafj2....==$storedkey:$serverkey

Copy the ENTIRE line.

Step 2 — Update PgBouncer’s `userlist.txt`

Open your local file:

pgbouncer/userlist.txt

Replace or add:

"myappuser" "SCRAM-SHA-256$4096:xxxxxxxxxx==$storedkey:$serverkey"

⚠️ Notes:

Quotes are mandatory.
No extra whitespace.
One user per line.

Step 3 — Restart PgBouncer

PgBouncer must reload after editing userlist.txt.

For Docker Compose:

docker compose restart pgbouncer

Or with the admin console:

psql -h localhost -p 6432 pgbouncer -c "RELOAD"

🧪 Step 4 — Test the connection

If it works, PgBouncer logs won’t show the error anymore and DBeaver / your app will connect normally.

🛑 Alternative (NOT recommended): Downgrade PostgreSQL to MD5

You may see this workaround online:

Set password_encryption = md5
Reset user passwords
Put MD5 hashes in userlist.txt

That works but reduces security and breaks alignment with modern PostgreSQL defaults.
Use SCRAM unless you have a legacy requirement.

🧩 Final Working Example

`userlist.txt`

"postgres" "SCRAM-SHA-256$4096:abcd123...$storedkey:$serverkey"
"myappuser" "SCRAM-SHA-256$4096:efgh456...$storedkey:$serverkey"

`pgbouncer.ini` snippet

auth_type = scram-sha-256
auth_file = /etc/pgbouncer/userlist.txt

🎉 Conclusion

The wrong password type error is simply a mismatch between:

PostgreSQL’s real password hash (SCRAM)
PgBouncer’s expected password entry (MD5 or SCRAM)

Fixing the issue is just a matter of:

Reading the real SCRAM hash from Postgres
Using it in PgBouncer’s userlist.txt
Restarting PgBouncer

Once aligned, PgBouncer works perfectly with PostgreSQL 14–18+.

If you want, I can also write:

✅ a downloadable example project (docker-compose + configs)
✅ an image diagram explaining the flow
✅ a troubleshooting checklist section

Just tell me!

🔒 Stop Downgrading Postgres: The Secure SCRAM Fix for PgBouncer Authentication

Milind Satpute — Tue, 09 Dec 2025 19:10:50 +0000

A secure, production-ready fix for the FATAL: server login failed: wrong password type error when connecting PgBouncer to a modern PostgreSQL database (v14+) using SCRAM-SHA-256 authentication.

If you are setting up a modern application stack with Docker Compose, PostgreSQL (v14+), and PgBouncer for connection pooling, you've likely hit this frustrating error in your logs or database client (like DBeaver):

FATAL: server login failed: wrong password type

This occurs because modern PostgreSQL defaults to the secure SCRAM-SHA-256 authentication method, but PgBouncer's default configuration often can't handle it seamlessly.

👎 The Common (and Flawed) Workaround: Downgrading to MD5

Many online guides suggest the quick fix: force your PostgreSQL container to use the deprecated MD5 method by adding environment variables like POSTGRES_HOST_AUTH_METHOD=md5.

# ⚠️ WARNING: DO NOT USE THIS FOR PRODUCTION!
postgres:
  # ...
  environment:
    # ...
    POSTGRES_HOST_AUTH_METHOD: md5 
    POSTGRES_INITDB_ARGS: --auth=md5

This works, but it forces your production-ready PostgreSQL server to use a weaker, outdated encryption standard.

🛡️ The Secure Solution: SCRAM Hash Transfer

The correct, production-grade fix is to let PostgreSQL keep its secure SCRAM-SHA-256 authentication and manually configure PgBouncer to use the exact SCRAM hash generated by PostgreSQL.

This approach keeps your database secure and resolves the "wrong password type" error.

Prerequisites: PgBouncer Setup

We will assume you are using the popular edoburu/pgbouncer image and have mapped a local userlist.txt file into the container.

1. Create the userlist.txt file
Create a local directory (e.g., ./pgbouncer) and an empty userlist.txt file inside it.

2. Update docker-compose.dev.yml
Ensure the volume mount is present on your pgbouncer service:

# docker-compose.dev.yml snippet
pgbouncer:
  image: ${PGBOUNCER_IMAGE} # e.g., edoburu/pgbouncer:latest
  # ... other config
  volumes:
    # Map the local file to the container path
    - ./pgbouncer/userlist.txt:/etc/pgbouncer/userlist.txt

Step 1: Get the SCRAM Hash from PostgreSQL

The first step is to retrieve the SCRAM-hashed password string for your database user from the PostgreSQL system tables.

Start your stack (the PgBouncer container will fail to connect for now, but that's fine):
```
docker-compose -f docker-compose.dev.yml --env-file .env.dev up -d
```
Connect to the PostgreSQL Container using docker exec and the psql client. (Adjust container name and user as needed from your .env.dev file, e.g., tnt_postgres_dev and tnt_admin).
```
docker exec -it tnt_postgres_dev psql -U tnt_admin -d tnt_dev
```

Execute the Query to Extract the Hash:
This query pulls the encrypted password from the pg_shadow table and prefixes it correctly for PgBouncer.

SELECT 'SCRAM-SHA-256$' || passwd FROM pg_shadow WHERE usename = 'tnt_admin';

Example Output:

                  ?column?
----------------------------------------------------------------------------------------------------------------------------------
SCRAM-SHA-256$2048:y+y1d/g.../z2+9eJ/1+Q==$:GzB3... # <--- COPY THIS ENTIRE STRING
(1 row)

Copy the entire string starting from SCRAM-SHA-256$.

Step 2: Manually Update `userlist.txt`

Edit your local pgbouncer/userlist.txt file and paste the copied hash. The format required by PgBouncer is:

"username" "hash_string"

./pgbouncer/userlist.txt

"tnt_admin" "SCRAM-SHA-256$2048:y+y1d/g.../z2+9eJ/1+Q==$:GzB3..."

Step 3: Final Restart and Connection

Stop and Recreate Containers:
You must stop the PgBouncer container and re-run up -d to load the newly updated userlist.txt.

docker-compose -f docker-compose.dev.yml --env-file .env.dev down
docker-compose -f docker-compose.dev.yml --env-file .env.dev up -d

Your PgBouncer service will now start and successfully use the secure SCRAM hash to authenticate with PostgreSQL. You can connect your application or database client (like DBeaver) to the PgBouncer port (e.g., 6432) using your original plaintext password.

This method successfully resolves the authentication issue while keeping your PostgreSQL security settings at the modern standard. Happy pooling!