quarkusio/quarkus · error · java.lang.IllegalStateException

Alias '${alias}' not found in JKS key store (certificate not

Error message

Alias '${alias}' not found in JKS key store (certificate not found)'${name}'

What it means

After loading the JKS key store, Quarkus verifies the configured alias. If KeyStore.getCertificate(alias) returns null, the alias does not exist (or holds no certificate entry), and this IllegalStateException is thrown at startup.

Source

Thrown at extensions/tls-registry/runtime/src/main/java/io/quarkus/tls/runtime/keystores/JKSKeyStores.java:113

                options.setAlias(config.alias().get());
            }
        } catch (UncheckedIOException e) {
            throw new IllegalStateException("Invalid JKS trust store configuration for certificate '" + name
                    + "' - cannot read the trust store file '" + config.path() + "'", e);
        } catch (Exception e) {
            throw new IllegalStateException("Invalid JKS trust store configuration for certificate '" + name + "'", e);
        }
        return options;
    }

    private static void verifyKeyStoreAlias(JksOptions options, String name, KeyStore ks) {
        String alias = options.getAlias();
        // Credential provider already called.
        String aliasPassword = options.getAliasPassword();
        if (alias != null) {
            try {
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in JKS key store (certificate not found)'" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in JKS key store '" + name + "'", e);
            }

            char[] ap = null;
            if (aliasPassword != null) {
                ap = aliasPassword.toCharArray();
            }

            try {
                if (ks.getKey(alias, ap) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in JKS key store (private key not found)'" + name + "'");
                }
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(

View on GitHub (pinned to e1c734241f)

Solutions

List the aliases in the JKS: keytool -list -keystore keystore.jks -storepass <password> and use an exact existing alias.
Fix the alias value in quarkus.tls.<name>.key-store.jks.alias.
If the keystore was regenerated, re-export/import the certificate so the expected alias exists.

Example fix

// before
quarkus.tls.my-cert.key-store.jks.alias=serveer
// after
quarkus.tls.my-cert.key-store.jks.alias=server

Defensive patterns

Strategy: validation

Validate before calling

KeyStore ks = KeyStore.getInstance("JKS");
try (var in = java.nio.file.Files.newInputStream(java.nio.file.Path.of(keystorePath))) {
    ks.load(in, storePassword.toCharArray());
}
boolean ok = ks.getCertificate(alias) != null;

Try / catch

try {
    // startup
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("not found in JKS key store")) {
        log.errorf("Alias %s missing; run: keytool -list -keystore keystore.jks", configuredAlias);
    }
    throw e;
}

Prevention

Run keytool -list and copy aliases exactly from its output.
Script keystore regeneration and config updates together.
Add an integration test that starts the app with the real keystore.
Treat aliases as config-managed values, not hand-typed strings.

When it happens

Trigger: quarkus.tls.<name>.key-store.jks.alias is set to a name that is absent from the JKS file; verification runs in verifyKeyStoreAlias (JKSKeyStores.java:112-114) during verifyJKSKeyStore.

Common situations: Alias typo or wrong case (JKS aliases are case-insensitive lowercased, PKCS12 differs); certificate regenerated under a different alias; keystore rotated without updating config; alias exists but only holds a key entry without certificate chain at first check.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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