Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

The postgres container exits at start and asks for a superuser password

ErrorError: 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.

  • 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

    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 20
  2. 2Match what you see, then jump to its fix

    1. 1docker compose config shows no POSTGRES_PASSWORD under the database servicePOSTGRES_PASSWORD is missing, misspelled or set on a different serviceFix
    2. 2docker 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. 3docker 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

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-passwd

3Verify

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 5

Confirmed by github.com

Did this fix it?

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_PASSWORD

2Fix

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 -d

3Verify

docker compose config now prints the real value, or fails early with your message.

docker compose config | grep -i postgres_password

Confirmed by docs.docker.com

Did this fix it?

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-postgres

2Fix

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:17

3Verify

docker inspect now lists POSTGRES_PASSWORD, and the container stays running.

docker inspect --format '{{.Config.Env}}' my-postgres
docker logs my-postgres --tail 5

Confirmed by docs.docker.com

Did this fix it?

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 fix

Next step

Want this handled for good?

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