quarkusio/quarkus · error · java.lang.IllegalArgumentException

Unable to recover the key for alias '${alias}' in JKS key st

Error message

Unable to recover the key for alias '${alias}' in JKS key store '${name}'

What it means

KeyStore.getKey(alias, aliasPassword) threw UnrecoverableKeyException — the key exists but could not be recovered, almost always because the alias password is wrong. Quarkus throws IllegalArgumentException with this message.

Source

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

            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) {
            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);
            }
        }
    }

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.tls.<name>.key-store.jks.alias-password to the exact key entry password (check with keytool -keypasswd history or the import source).
If unknown, reset it: keytool -keypasswd -alias <alias> -keystore keystore.jks, or re-import the key with the store password as entry password.
Use a credential provider or env var expansion for the password instead of hardcoding, avoiding escaping issues.

Example fix

// before
quarkus.tls.my-cert.key-store.jks.password=storepass
# alias-password missing but key entry password is 'keypass'
// after
quarkus.tls.my-cert.key-store.jks.password=storepass
quarkus.tls.my-cert.key-store.jks.alias-password=keypass

Defensive patterns

Strategy: validation

Validate before calling

boolean keyRecoverable;
try {
    KeyStore ks = KeyStore.getInstance("JKS");
    try (var in = java.nio.file.Files.newInputStream(java.nio.file.Path.of(keystorePath))) {
        ks.load(in, storePassword.toCharArray());
    }
    keyRecoverable = ks.getKey(alias, aliasPassword.toCharArray()) != null;
} catch (java.security.UnrecoverableKeyException e) {
    throw new IllegalStateException("Wrong alias-password for " + alias, e);
}

Try / catch

try {
    // startup
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unable to recover the key")) {
        log.errorf("Wrong quarkus.tls.<name>.key-store.jks.alias-password for alias %s", alias);
    }
    throw e;
}

Prevention

Store key entry password in a secret/env var and inject it, not inline.
After re-importing keys, always re-test with the new entry password.
Keep entry password == store password unless policy requires otherwise.
Rotate secrets in coordination with keystore regeneration.

When it happens

Trigger: quarkus.tls.<name>.key-store.jks.alias-password does not match the password the key entry was created with; verifyKeyStoreAlias (JKSKeyStores.java:136-138) during verifyJKSKeyStore.

Common situations: Key imported with a per-entry password different from the store password; alias-password property omitted while key was created with a non-default entry password; rotated secrets in Kubernetes; special characters in the password not escaped in properties.

Related errors

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