Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Postgres in Docker says the role "root" does not exist

ErrorFATAL: role "root" does not exist

Short answer

Postgres is telling you that something connected as the operating system user root, and no database role with that name exists. The caller sent no user name. It is usually a healthcheck written as bare pg_isready, or a client run inside the container without -U. Pass the real role name.

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

Fix it fast

  1. 1Find out which cause you have

    Look at the lines around the error in the container log. Repeating every few seconds points to a healthcheck. A single line right after you ran a command points to that command.

    docker compose logs --timestamps db | grep -B2 -A2 'role "root"'
  2. 2Match what you see, then jump to its fix

    1. 1The error repeats at the healthcheck interval.A healthcheck calls pg_isready without a userFix
    2. 2The error appears once, right after docker exec or docker compose exec.A command inside the container runs as root without -UFix
    3. 3Connecting with -U postgres gives 'role "postgres" does not exist'.POSTGRES_USER was changed, so the role postgres is absentFix

What does the error look like?

  • FATAL: role "root" does not exist
  • psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL: role "root" does not exist

Cause 1 of 3

A healthcheck calls pg_isready without a user

1Check

pg_isready connects as the default user when -U is missing (its manual: 'instead of the default'). The libpq default is the operating system user, which in a container is root, so each probe is logged as a failed login for a role that does not exist.

grep -n -A6 healthcheck compose.yaml

2Fix

Give the probe the real user and database.

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
  interval: 10s
  timeout: 5s
  retries: 5

3Verify

Recreate the container; the repeating error stops and the status becomes healthy.

docker compose up -d --force-recreate db
docker compose ps

Confirmed by postgresql.org

Did this fix it?

Cause 2 of 3

A command inside the container runs as root without -U

1Check

docker exec starts as the image's user unless you override it, and psql uses that name as the role. Compose runs a process as root when the image sets no user.

docker compose exec db psql -c 'select current_user'

2Fix

Name the role explicitly. It is the POSTGRES_USER you set, or postgres when you did not set one.

docker compose exec db psql -U postgres -d postgres

3Verify

The prompt opens and current_user shows the role.

docker compose exec db psql -U postgres -c 'select current_user'

Confirmed by hub.docker.com

Did this fix it?

Cause 3 of 3

POSTGRES_USER was changed, so the role postgres is absent

1Check

The image creates the superuser named in POSTGRES_USER on the first start. Without that variable it uses postgres.

docker compose exec db env | grep POSTGRES_USER

2Fix

Use the user name from POSTGRES_USER in every client, healthcheck and connection string.

docker compose exec db psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"

3Verify

The command connects.

docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "select 1"'

Confirmed by hub.docker.com

Did this fix it?

How do I stop it coming back?

  • Always write -U (and -d) in healthchecks and scripts.
  • Keep user and database names in one .env file used by every service.

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.