quarkusio/quarkus · critical · RuntimeException

Failed to create Keycloak Admin client SSLContext

Error message

Failed to create Keycloak Admin client SSLContext

What it means

When Quarkus builds the internal Keycloak Admin REST client at startup, it configures TLS from the named TLS registry configuration (truststore, keystore, trust-all). If namedTlsConfig.createSSLContext() throws for any reason, the recorder wraps it in a RuntimeException 'Failed to create Keycloak Admin client SSLContext', aborting application startup. It means the TLS configuration for the admin client is invalid.

Source

Thrown at extensions/keycloak-admin-resteasy-client/runtime/src/main/java/io/quarkus/keycloak/admin/resteasy/client/runtime/KeycloakAdminResteasyClientRecorder.java:105

            @Override
            public Client newRestEasyClient(Object customJacksonProvider, SSLContext sslContext, boolean disableTrustManager) {
                // this is what 'org.keycloak.admin.client.ClientBuilderWrapper.create' does
                var builder = new ResteasyClientBuilderImpl();
                builder.connectionPoolSize(10);

                if (namedTlsConfig == null) {
                    builder.sslContext(sslContext);
                    if (globalTrustAll) {
                        builder.disableTrustManager();
                    }
                } else {
                    if (namedTlsConfig.isTrustAll()) {
                        builder.disableTrustManager();
                    }
                    try {
                        builder.sslContext(namedTlsConfig.createSSLContext());
                    } catch (Exception e) {
                        throw new RuntimeException("Failed to create Keycloak Admin client SSLContext", e);
                    }
                }

                // this ensures we don't customize managed (shared) ObjectMapper available in the CDI container
                // and that we use QuarkusJacksonSerializer that works in native mode
                builder.register(new AppJsonQuarkusJacksonSerializer(), 100);

                return builder.build();
            }

            @Override
            public <R> R targetProxy(WebTarget webTarget, Class<R> aClass) {
                return (ResteasyWebTarget.class.cast(webTarget)).proxy(aClass);
            }
        });
    }

    public void avoidRuntimeInitIssueInClientBuilderWrapper() {

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the keystore/truststore paths, passwords, and types in the quarkus.keycloak.admin-client.tls (or named TLS registry) config; check the cause chain for the exact KeyStoreException
2. If no custom TLS is needed, remove the tls configuration so defaults are used, or set trust-all=true for dev/test
3. Ensure the certificate files are packaged/available at runtime (e.g. in the container image) with correct permissions
4. Validate certificates are not expired and the format matches the configured type

Example fix

// before
quarkus.keycloak.admin-client.tls.trust-store-file=/secrets/wrong.p12
// after
quarkus.keycloak.admin-client.tls.trust-store-file=/secrets/truststore.p12
quarkus.keycloak.admin-client.tls.trust-store-password=secret
quarkus.keycloak.admin-client.tls.trust-store-type=PKCS12

// Validate TLS config files before startup:
String tsPath = config.getValue("quarkus.keycloak.admin-client.tls.trust-store-file");
String tsPass = config.getValue("quarkus.keycloak.admin-client.tls.trust-store-password");
String tsType = config.getValue("quarkus.keycloak.admin-client.tls.trust-store-type");
try (InputStream in = new FileInputStream(tsPath)) {
    KeyStore.getInstance(tsType != null ? tsType : "PKCS12").load(in, tsPass.toCharArray());
} catch (Exception e) {
    throw new IllegalStateException("Invalid truststore for Keycloak admin client", e);
}

try {
    Keycloak keycloak = keycloakAdminClientCreator.create(); // startup phase
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("Failed to create Keycloak Admin client SSLContext")) {
        log.errorf(e.getCause(), "Check keystore/truststore path, password, and type in quarkus.keycloak.admin-client.tls.*");
    }
    throw e;
}

When it happens

Trigger: A quarkus.keycloak.admin-client.tls configuration referencing a truststore/keystore file that doesn't exist, has a wrong password, or an unsupported format; an invalid TLS configuration key; or an underlying KeyStore/SSLContext initialization exception.

Common situations: Path typos or non-mounted secrets in containerized/native deployments; wrong keystore type (PKCS12 vs JKS) or password after rotating credentials; misconfigured quarkus.tls.* named config used by the admin client.

Related errors

• Trust options have already been set
• Key cert options have already been set
• Hostname verification failure
• Failed to load truststore
• Failed to load keystore

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/0f7c2f0ac59a1a40. Report an issue: GitHub.