The postgres container exits at start and asks for a superuser password
Error: Database is uninitialized and superuser password is not specified.Short answer
The official postgres image refuses to create a new database without a password for the superuser. POSTGRES_PASSWORD must be present and not empty in the environment of the postgres container itself. It is missing, misspelled, on the wrong service, empty after Compose substitution, or placed after the image name in docker run.
Fix it fast
1Find out which cause you have
Print what Compose will really hand to the container. If POSTGRES_PASSWORD is absent from the postgres service, or shows as an empty string, you have found the problem.
docker compose config | grep -n -i -B2 -A2 postgres_password docker compose logs db --tail 202Match what you see, then jump to its fix
- 1
docker compose config shows no POSTGRES_PASSWORD under the database servicePOSTGRES_PASSWORD is missing, misspelled or set on a different serviceFix - 2
docker compose config prints POSTGRES_PASSWORD with an empty value, while the compose file looks rightThe value comes from ${...} and Compose replaced it with an empty stringFix - 3
docker compose is not used, and the command line ends in postgres -e POSTGRES_PASSWORD=...With docker run, the -e flag was written after the image nameFix
- 1
What does the error look like?
Error: Database is uninitialized and superuser password is not specified.the postgres container exits right after it starts, and docker compose ps lists it as exited
Cause 1 of 3
POSTGRES_PASSWORD is missing, misspelled or set on a different service
1Check
The image documents POSTGRES_PASSWORD as required for the image, and says it must not be empty or undefined. The usual slips are a variable with another name, or a value placed under the application service instead of the database service. Look at the service that runs the postgres image.
docker compose config | grep -n -E "image: |POSTGRES_"2Fix
Set the variable on the postgres service. For a throwaway local database you can instead use the trust method, which the image's own notes advise against because it lets anyone connect without a password. For real use, point POSTGRES_PASSWORD_FILE at a secret file.
services:
db:
image: postgres:17
environment:
POSTGRES_PASSWORD: change-me-example
# or, with a secret file:
# environment:
# POSTGRES_PASSWORD_FILE: /run/secrets/postgres-passwd3Verify
Recreate the container. It now stays up, and its log no longer ends with the error.
docker compose up -d db
docker compose logs db --tail 5Confirmed by github.com
Cause 2 of 3
The value comes from ${...} and Compose replaced it with an empty string
1Check
If a variable used in compose.yaml is not set, Compose substitutes an empty string. It reads the .env file from the project directory, which is the folder of compose.yaml, or your current folder otherwise. Running the command from another folder, or a .env file with a different name, leaves the value empty.
ls -a | grep -E "^\.env"
docker compose config --environment | grep -i DB_PASSWORD2Fix
Put the .env file next to compose.yaml, name the file with --env-file if it lives elsewhere, and make the compose file stop with a clear message when the value is missing.
# compose.yaml
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD is not set}
# shell
docker compose --env-file ./config/.env.dev up -d3Verify
docker compose config now prints the real value, or fails early with your message.
docker compose config | grep -i postgres_passwordConfirmed by docs.docker.com
Cause 3 of 3
With docker run, the -e flag was written after the image name
1Check
The syntax of docker run is options first, then the image, then an optional command and its arguments. A flag after the image name is passed to the container's command, so the container never receives the variable.
docker inspect --format '{{.Config.Env}}' my-postgres2Fix
Move every option in front of the image name, remove the failed container and start it again.
docker rm -f my-postgres
docker run --name my-postgres -e POSTGRES_PASSWORD=change-me-example -d postgres:173Verify
docker inspect now lists POSTGRES_PASSWORD, and the container stays running.
docker inspect --format '{{.Config.Env}}' my-postgres
docker logs my-postgres --tail 5Confirmed by docs.docker.com
How do I stop it coming back?
- Keep one compose file for the database that always sets POSTGRES_PASSWORD, and share it with the team through a .env.example file with a dummy value.
- Use ${VAR:?message} for every secret in compose.yaml, so a missing value stops the start with a readable error.
- Run docker compose config in CI and fail the job if the database service has no password.
- Remember that these variables only matter on first start with an empty data directory; changing them later does not change an existing database.
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
The Postgres container rejects the password you set in POSTGRES_PASSWORD
psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL: password authentication failed for user "postgres"
The official Postgres image reads POSTGRES_PASSWORD only when it creates a new database cluster in an empty data directory.
2 causes, each with a fixDatabases
The Postgres container refuses to start: data directory has invalid permissions
mkdir: cannot create directory ‘/home/postgres/pgdata/data’: permission denied
Postgres starts only when its data directory is owned by the server user and closed to everyone else: mode 0700, or 0750 when group read is enabled.
3 causes, each with a fixDatabases
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 fix