quarkusio/quarkus · error · java.lang.IllegalStateException

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

Error message

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

What it means

Thrown by JKSKeyStores.verifyTrustStoreAlias when a JKS trust store was loaded successfully but the configured alias has no certificate in it (ks.getCertificate(alias) returned null). The alias option names a specific entry to pin; the guard fires after load, wrapped together with KeyStoreException/NoSuchAlgorithmException handling in the 'Unable to verify alias' path, and names both the missing alias and the trust store configuration name.

Source

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

                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in JKS key store (certificate not found)'" + name + "'");
                }
            } catch (KeyStoreException | NoSuchAlgorithmException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in JKS key store '" + name + "'", e);
            } catch (UnrecoverableKeyException e) {
                throw new IllegalArgumentException(
                        "Unable to recover the key for alias '" + alias + "' in JKS key store '" + name + "'", e);
            }
        }
    }

    private static void verifyTrustStoreAlias(JksOptions options, String name, KeyStore ks) {
        String alias = options.getAlias();
        if (alias != null) {
            try {
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in JKS trust store (certificate not found)'" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in JKS trust store '" + name + "'", e);
            }
        }
    }

    private static KeyStore loadKeyStore(Vertx vertx, String name, JksOptions options, String type) {
        try {
            return options.loadKeyStore(vertx);
        } catch (Exception e) {
            throw new IllegalStateException("Unable to load JKS " + type + " store '" + name + "', verify the password.", e);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

List aliases: keytool -list -keystore truststore.jks and correct quarkus.tls.<name>.trust-store.jks.alias.
Re-import the CA certificate under the expected alias: keytool -importcert -alias <alias> -file ca.crt -keystore truststore.jks.
Remove the alias property entirely if trusting all entries in the store is intended.

Example fix

// before
quarkus.tls.my-cert.trust-store.jks.alias=internal-ca-v1
// after
quarkus.tls.my-cert.trust-store.jks.alias=internal-ca

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Copy aliases from keytool -list output, never by hand.
Rebuild trust stores via script that also updates config.
Omit the alias property to trust all entries in the store.
Pin trust store contents in version control or a managed secret.

When it happens

Trigger: quarkus.tls.<name>.trust-store.jks.alias names an alias absent from the trust store; verifyTrustStoreAlias (JKSKeyStores.java:147-149) during verifyJKSTrustStoreStore.

Common situations: Trusted CA imported under a different alias than configured; trust store rebuilt/replaced losing the alias; alias case/format mismatch; copy-pasted key-store alias into the trust-store config.

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/37dc99230e0936fe. Report an issue: GitHub.