quarkusio/quarkus · error · java.lang.IllegalStateException

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

Error message

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

What it means

When a private-key alias is configured, Quarkus checks KeyStore.getKey(alias, aliasPassword). If it returns null the alias does not hold a private key, so startup fails with this IllegalStateException.

Source

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

        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(
                            "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) {

View on GitHub (pinned to e1c734241f)

Solutions

Run keytool -list -v -keystore keystore.jks and confirm the alias is a PrivateKeyEntry, not TrustedCertEntry.
Set quarkus.tls.<name>.key-store.jks.alias-password correctly (it often differs from the store password).
If the entry is cert-only, import the full key+cert chain with keytool -importkeystore from the P12/PKCS12 original.

Example fix

// before
quarkus.tls.my-cert.key-store.jks.alias=ca-root
// after
quarkus.tls.my-cert.key-store.jks.alias=server
quarkus.tls.my-cert.key-store.jks.alias-password=keypass

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 hasKey = ks.isKeyEntry(alias);

Try / catch

try {
    // startup
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("private key not found")) {
        log.errorf("Alias %s is not a PrivateKeyEntry; check keytool -list -v", alias);
    }
    throw e;
}

Prevention

Confirm with keytool -list -v that the alias is a PrivateKeyEntry.
Set alias-password whenever the key entry password differs from the store password.
Import full PKCS12 bundles rather than bare keys.

When it happens

Trigger: quarkus.tls.<name>.key-store.jks.alias points to an alias that exists but contains no private key entry (e.g. a trusted-cert-only entry), or alias-password is wrong such that getKey resolves to nothing; verifyKeyStoreAlias (JKSKeyStores.java:126-128) during verifyJKSKeyStore.

Common situations: Pointing the key-store alias at a trust/cert entry instead of the server key entry; copying an alias into the wrong keystore; alias password omitted or wrong so the key cannot be retrieved (some stores return null instead of throwing).

Related errors

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