Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

The Postgres container rejects the password you set in POSTGRES_PASSWORD

ErrorFATAL: password authentication failed for user "postgres"

Short answer

The official Postgres image reads POSTGRES_PASSWORD only when it creates a new database cluster in an empty data directory. If the volume already holds a cluster, the variable is ignored and the old password stays. A second cause is that you are talking to a different Postgres on the same host port.

  • Applies to postgres Docker image 17 and 18, Docker Engine 28, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the container's data volume already existed before this start. If the startup log says the database directory was already initialised, the password variable was not applied.

    docker compose logs db | head -n 20
    docker volume ls
  2. 2Match what you see, then jump to its fix

    1. 1The log shows no initialisation steps, and the old password still works.The volume already holds a database, so the new password was never appliedFix
    2. 2The container log shows no failed login at all, yet the client says the password is wrong.Your client reaches another Postgres on the same host portFix

What does the error look like?

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

Cause 1 of 2

The volume already holds a database, so the new password was never applied

1Check

You changed POSTGRES_PASSWORD (or the compose file) after the first start. The image sets the password once, while it initialises an empty data directory, and leaves an existing cluster alone.

docker compose logs db | grep -i -E "initdb|init process"
docker compose exec db env | grep POSTGRES_

2Fix

If the data is disposable, delete the volume so the next start initialises again with the new value. If you need the data, keep the volume and set the password inside the running database.

# disposable data: this deletes the database
docker compose down -v
docker compose up -d

# keep the data
docker compose exec db psql -U postgres -c "ALTER USER postgres PASSWORD 'new-password';"

3Verify

Connect with the new password over TCP, which is the path that checks it.

PGPASSWORD='new-password' psql -h 127.0.0.1 -U postgres -c 'select 1'

Confirmed by hub.docker.com

Did this fix it?

Cause 2 of 2

Your client reaches another Postgres on the same host port

1Check

A Postgres installed on the host can already own port 5432, so the published container port does not receive your connection. Look at what listens on the host port and what the compose file publishes.

lsof -nP -iTCP:5432 -sTCP:LISTEN
docker compose port db 5432

2Fix

Publish the container on a free host port and connect to that port, or stop the host server.

services:
  db:
    image: postgres:17
    ports:
      - "5433:5432"

3Verify

Connect to the new host port and run a query.

PGPASSWORD='your-password' psql -h 127.0.0.1 -p 5433 -U postgres -c 'select 1'

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Treat POSTGRES_PASSWORD as a first-start setting; change passwords later with ALTER USER.
  • Name the volume in the compose file so you always know which one holds the data.
  • Publish the container on a port that is not 5432 when a local Postgres exists.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.