The Postgres container rejects the password you set in POSTGRES_PASSWORD
FATAL: 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.
Fix it fast
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 ls2Match what you see, then jump to its fix
- 1
The 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
The 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
- 1
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
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 54322Fix
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
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
Databases
Django cannot connect to PostgreSQL: connection refused on port 5432, locally or in Docker
Is the server running on that host and accepting TCP/IP connections?
Connection refused means nothing accepted the connection at the host and port Django used.
4 causes, each with a fixDatabases
Node.js in Docker Compose cannot find mysql2/promise
The app works on the host but fails after docker compose up
mysql2/promise is a path inside the mysql2 package.
2 causes, each with a fixDatabases
A container cannot resolve the name of its database container
php_network_getaddresses: getaddrinfo failed
127.0.0.11 is Docker's own DNS server for custom networks.
3 causes, each with a fixDatabases
EF Core says 'transient failure' when it cannot reach PostgreSQL in Docker
The query fails only after a delay, because the connection is retried several times
The transient failure message comes from EF Core's retry layer, which hides the underlying connection error.
3 causes, each with a fixDatabases
Keycloak in a container will not let you create the first admin user
You need local access to create the initial admin user.
Keycloak only lets you create the first admin from a local network connection, and a container does not count.
2 causes, each with a fixDatabases
The MariaDB or MySQL container ignores the root password you set
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
The official MariaDB and MySQL images apply their password variables only while initialising an empty data directory.
3 causes, each with a fix