Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Keycloak in a container will not let you create the first admin user

ErrorYou 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.

  • Applies to Keycloak 26, Docker Engine 28, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1The env check prints nothing.The bootstrap admin variables are missingFix
    2. 2The variables are set, but no admin is created and the old database is reused.The database already has a master realmFix

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.yaml

2Fix

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

3Verify

Sign in to the admin console with those credentials.

curl -I http://localhost:8080/admin/

Confirmed by keycloak.org

Did this fix it?

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 master

2Fix

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_VAR

3Verify

Start Keycloak and sign in with the temporary account.

docker compose up -d keycloak

Confirmed by keycloak.org

Did this fix it?

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

Next step

Want this handled for good?

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