SaaS architecture
role "root" or "postgres" does not exist: causes, fixes
PostgreSQL's role does not exist, measured on 17: psql as root in Docker, POSTGRES_USER on a reused volume, quoted names, GRANT, SET ROLE and pg_restore.
Now-Next builds SaaS products and takes over existing ones. What we build
FATAL: role "root" does not exist (SQLSTATE 28000, invalid_authorization_specification) means the server has no role with exactly the name the client logged in with. The name need not be one you typed: psql takes your operating-system user name when you give no -U, and inside a Docker container that is root. The same text as an ERROR (42704) comes from a statement such as GRANT or ALTER … OWNER TO that names a role that is not there.
We measured on the official Docker images postgres:17 (PostgreSQL 17.11) and postgres:12 (12.22), for the database error also postgres:18 (18.6), with a psql 16.15 client on the host. The connection error’s SQLSTATE does not appear in psql’s output, so we read it from the server log with %e in log_line_prefix.
Where did the client connect?
- Inside the container,
docker exec … psqlwithout-Urole "root" does not existpsql used your operating-system user. Add-U, ordocker exec -u postgres. - Inside the container (socket or
127.0.0.1,trust), with-Urole "…" does not existThe client sees the real reason. CheckPOSTGRES_USERand capitals in the name. - From the host, through the published port (
scram-sha-256)password authentication failed for user "…"Onlydocker logsshowsDETAIL: Role "…" does not exist.Without that line the role exists, and the password is the problem (wrong, not set or expired; the log says which for the last two).
Official image postgres:17 (17.11), default pg_hba.conf; the root case was the same on postgres:12. A role without LOGIN gave a third message, role "…" is not permitted to log in: inside the container, and from the host only with the correct password.
Why does psql say role “root” does not exist?
Because it connects as the user you are. In a container, docker exec runs as root:
-- docker exec -it c psql
-- psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed:
-- FATAL: role "root" does not exist
-- server log: sqlstate=28000
Adding -d postgres did not help; the role is the problem, not the database. On PostgreSQL 12 the message was identical. docker exec -u postgres c psql connected as postgres to database postgres. The psql documentation states the rule: “The default database user name is your operating-system user name. Once the database user name is determined, it is used as the default database name.” PGUSER overrides it.
That second sentence is the next error. After we created a role chris (our host user name) and connected without naming a database, the role was fine and the database was not:
-- psql -h 127.0.0.1 -p 55501
-- FATAL: database "chris" does not exist (sqlstate 3D000)
-- psql -h 127.0.0.1 -p 55501 postgres -> current_user = chris, current_database = postgres
Why does it say password authentication failed instead?
From the host, through the published port, a missing role did not produce role does not exist. The official image’s pg_hba.conf ends in host all all all scram-sha-256, and for that line the client only got FATAL: password authentication failed for user "chris" (SQLSTATE 28P01). The real reason was only in the server log:
-- FATAL: password authentication failed for user "chris"
-- DETAIL: Role "chris" does not exist.
-- Connection matched file "/var/lib/postgresql/data/pg_hba.conf" line 128: "host all all all scram-sha-256"
Inside the container, over the Unix socket or 127.0.0.1 (both trust in that file), the same missing role gave role "…" does not exist. So whether you see this error or a password error depends on the authentication method, not on the role: docker logs tells you which it is. With an existing role and a wrong password, the client message was identical; only the missing Role "…" does not exist. DETAIL line in docker logs told the two apart. The other causes behind that message are in password authentication failed for user.
Why does role “postgres” not exist in my Docker container?
Because POSTGRES_USER replaces it. With POSTGRES_USER=app and no POSTGRES_DB, the only non-system role was app (a superuser), and the databases were postgres, app, template1 and template0. psql -U postgres then failed with FATAL: role "postgres" does not exist inside the container, and with password authentication failed for user "postgres" from the host.
The Docker Compose variant: the variables only act on an empty data directory. We recreated the container on the same named volume with POSTGRES_USER=newuser, POSTGRES_PASSWORD=pw2 and POSTGRES_DB=newdb. The log said PostgreSQL Database directory appears to contain a database; Skipping initialization, and:
-- docker exec c psql -U newuser
-- FATAL: role "newuser" does not exist
-- roles: app only; databases: postgres, app, template1, template0 (no newdb)
-- psql -U app with the OLD password: works; with the new one: password authentication failed
Changing the variables in docker-compose.yml changed nothing in the database. Either create the role yourself (create role newuser login password '…') or, if the data is disposable, start on a new, empty volume: on a fresh volume with POSTGRES_USER=newuser and POSTGRES_DB=newdb, both were created. Pass -d newdb as well: without it psql looked for a database newuser and failed with database "newuser" does not exist.
Why does psql say database does not exist?
FATAL: database "app" does not exist (SQLSTATE 3D000, invalid_catalog_name) means the role exists and authentication succeeded, but there is no database with exactly that name. The name need not be one you typed: psql and libpq use the user name as the database name when none is given, so psql -U app looks for a database app. In Docker, a second cause is a POSTGRES_DB that was never created because the volume already held data.
-- role app exists, database app does not (PostgreSQL 17.11; 12.22 the same)
-- psql -h 127.0.0.1 -p 55841 -U app
-- psql: error: connection to server at "127.0.0.1", port 55841 failed:
-- FATAL: database "app" does not exist (exit code 2)
-- server log:
-- sqlstate=00000 user=app db=app LOG: connection authorized: user=app database=app
-- sqlstate=3D000 user=app db=app FATAL: database "app" does not exist
The server log has it too, with 3D000 when %e is in log_line_prefix. What else gave the same message on 17.11:
| What we ran | Result |
|---|---|
PGDATABASE=missing psql -U postgres | database "missing" does not exist |
psql 'postgresql://postgres:…@127.0.0.1:55841/missing' | the same: the path in the URL is the database name |
create database "MyApp", then psql -d MyApp | connected to MyApp: a connection parameter is not folded |
psql -d myapp | database "myapp" does not exist |
drop database MyApp (unquoted) | ERROR: 3D000: database "myapp" does not exist |
drop database missing | ERROR: 3D000, the same text, now as an ERROR |
drop database if exists missing | NOTICE: database "missing" does not exist, skipping, no error |
\c missing in interactive psql | the FATAL, then Previous connection kept |
\c missing in a script run with psql -f | the script stopped, exit code 2 |
psql -d template0 | a different error: database "template0" is not currently accepting connections (55000) |
DROP DATABASE, with and without IF EXISTS, behaved on 12.22 and 18.6 as on 17.11. The POSTGRES_DB case is the Compose trap from the section above, now seen from the database side: on 17.11 and 18.6 (from 18 the image keeps its data under /var/lib/postgresql/18/docker, so mount the volume at /var/lib/postgresql), a reused volume with POSTGRES_DB=newdb logged Skipping initialization, and psql -d newdb failed with database "newdb" does not exist. On a fresh volume, POSTGRES_USER=app without POSTGRES_DB created a database app; POSTGRES_DB=shop without POSTGRES_USER created shop next to postgres.
Is the role or the database checked first?
The role, and authentication before both. With a missing role and a missing database at once, the Unix socket (trust) gave role "nosuch" does not exist on 12.22, 17.11 and 18.6. From the host (scram-sha-256 on 17 and 18, md5 on 12) the same attempt gave password authentication failed for user "nosuch", and so did an existing role with a wrong password, as in why it says password authentication failed: the database name was never looked at. Only after connection authorized in the log did the server check the database. So database … does not exist tells you the role exists and authentication succeeded (with trust there was no password to check).
How do you see the databases and create the missing one?
Connect to a database that does exist — postgres, or template1 if postgres is gone — and list them:
-- psql -U postgres -d postgres
select datname, datallowconn from pg_database order by 1;
-- MyApp | t postgres | t template0 | f template1 | t
create database app; -- a role without CREATEDB got: permission denied to create database
\l shows the same list, but our host’s psql 16.15 failed on it against a 17.11 server with ERROR: column d.daticulocale does not exist; the psql inside the container (17.11) listed the databases normally, and the query above works with either. The createdb command line tool does the connecting for you: after we dropped postgres, a plain psql failed with database "postgres" does not exist, while createdb other succeeded, and the log showed it trying postgres first and then template1. createdb CliApp kept the capitals. In Docker, creating the database yourself is the fix for a reused volume. The alternative is a new, empty volume: the container then no longer sees the old data, and docker compose down -v or docker volume rm deletes it for good, so take a pg_dump first.
Why does a role with capitals not exist?
SQL folds unquoted names to lower case; the -U option does not. We created "App" (quoted) and Mixed (unquoted, stored as mixed):
| What you ran | Result |
|---|---|
psql -U App | connected as App |
psql -U app | FATAL: role "app" does not exist |
psql -U Mixed | FATAL: role "Mixed" does not exist |
psql -U mixed | connected as mixed |
psql -U '"App"' | FATAL: role ""App"" does not exist |
grant … to app | ERROR: 42704: role "app" does not exist |
grant … to "App" | GRANT |
A name in a connection string is taken literally; a name in SQL needs double quotes if it has capitals. The same folding causes relation does not exist for tables.
Which statements give role does not exist as an ERROR?
All of these named a role nosuch that did not exist. PostgreSQL 12.22 gave the same codes.
| Statement | SQLSTATE |
|---|---|
grant select on t to nosuch | 42704 |
alter table t owner to nosuch | 42704 |
alter role nosuch rename to x, drop role nosuch | 42704 |
select 'nosuch'::regrole, has_table_privilege('nosuch', …) | 42704 |
set role nosuch, set session authorization nosuch | 22023 (invalid_parameter_value) |
drop role if exists nosuch | NOTICE … skipping, no error |
The SET ROLE row matters if you catch errors by code: the text is the same, the SQLSTATE is not. The other codes are listed in our measured SQLSTATE overview.
Why does pg_restore say role does not exist?
A dump records owners and grants by role name, and roles are not part of pg_dump. We dumped a table owned by tenant_owner with a GRANT SELECT … TO reporting and restored it into a server that had only app:
-- pg_restore -d dst1 src.dump
-- pg_restore: error: could not execute query: ERROR: role "tenant_owner" does not exist
-- Command was: ALTER TABLE public.invoices OWNER TO tenant_owner;
-- pg_restore: error: could not execute query: ERROR: role "reporting" does not exist
-- Command was: GRANT SELECT ON TABLE public.invoices TO reporting;
-- pg_restore: warning: errors ignored on restore: 2 (exit code 1)
The table and its row were restored anyway, owned by app; only the ownership and the grant were lost. With --no-owner --no-privileges the restore was silent and exited 0; with only --no-owner the GRANT error remained. With -1 (single transaction) the first error rolled everything back: no table at all. If the roles should exist on the target, pg_dumpall --roles-only on the source wrote the CREATE ROLE statements, including the NOLOGIN role reporting. Restoring a single tenant has its own catches, which we covered in pg_dump of one tenant.
How do you see which roles exist?
\du in psql, or a query on pg_roles. In the container started with POSTGRES_USER=app:
\du
-- Role name | Attributes
-- app | Superuser, Create role, Create DB, Replication, Bypass RLS
select rolname, rolcanlogin from pg_roles where rolname !~ '^pg_';
-- app | t
\du hides the 15 predefined pg_* roles that PostgreSQL 17.11 had; the query above filters them out too. Check rolcanlogin: a role that exists but cannot log in gave a different error, FATAL: role "nologin_r" is not permitted to log in. Once the role exists, the next error can be about its rights — see permission denied for schema public.
What we did not measure
Windows installers and their default postgres user, Homebrew or distribution packages, managed databases, pg_ident.conf user-name maps, and LDAP or peer authentication. We did not measure psql clients other than 16.15 (apart from the psql inside the containers), drivers other than libpq, nor --role on pg_restore. For database does not exist we did not measure docker-entrypoint-initdb.d scripts on a reused volume, nor CREATE DATABASE on 12 or 18.
Sources: PostgreSQL 17 documentation on psql (default user and database name), read on 22 October 2026; connection parameters (dbname “Defaults to be the same as the user name”), environment variables (PGDATABASE), createdb (--maintenance-db) and DROP DATABASE, read on 27 October 2026. All measurements are our own, on PostgreSQL 17.11 and 12.22 in the official Docker images, on 22 October 2026; the database error on 17.11, 12.22 and 18.6 on 27 October 2026.