Keycloak in a container will not let you create the first admin user
You need local access to create the initial admin user.Short answer
Keycloak only lets you create the first admin from a local network connection, and a container does not count. Pass KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD on the first start. If the database already has a master realm, run the bootstrap-admin command instead.
Fix it fast
1Find out which cause you have
Check which admin variables the container actually received, and whether the database was used before.
docker compose exec keycloak env | grep KC_BOOTSTRAP docker compose logs keycloak | grep -i -E 'admin|master'2Match what you see, then jump to its fix
What does the error look like?
You need local access to create the initial admin user.
Cause 1 of 2
The bootstrap admin variables are missing
1Check
When Keycloak runs in a container you must supply the initial admin through environment variables, because the container network does not count as local.
grep -n KC_BOOTSTRAP compose.yaml2Fix
Add both variables, then restart so the first start creates the account.
services:
keycloak:
image: quay.io/keycloak/keycloak:26.0
command: start-dev
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: change-me3Verify
Sign in to the admin console with those credentials.
curl -I http://localhost:8080/admin/Confirmed by keycloak.org
Cause 2 of 2
The database already has a master realm
1Check
Bootstrap accounts are only created on the first start, when the master realm does not exist yet.
docker compose logs keycloak | grep -i master2Fix
Stop every Keycloak node and run the dedicated command with the same database options.
docker compose stop keycloak
docker compose run --rm keycloak bootstrap-admin user --username tmpadm --password:env PASS_VAR3Verify
Start Keycloak and sign in with the temporary account.
docker compose up -d keycloakConfirmed by keycloak.org
How do I stop it coming back?
- Replace the temporary admin with a permanent one and remove the temporary account.
- Keep the bootstrap password in a secret, not in a committed compose file.
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
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 fixDatabases
mongodb-memory-server will not start under Jest or in Docker
NoSystemBinaryFoundError
When mongodb-memory-server fails to start, the real reason is hidden behind a generic message.
4 causes, each with a fix