quarkusio/quarkus · error · java.lang.IllegalArgumentException

Unable to recover the key for alias

Error message

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

What it means

KeyStore.getKey(alias, pwd) threw UnrecoverableKeyException, meaning the private key for the alias exists but could not be recovered with the supplied alias password. Quarkus throws this IllegalArgumentException.

Solutions

1. Set quarkus.tls.<name>.key-store.p12.alias-password to the correct key entry password
2. If key and store passwords are identical, align or remove the alias-password override
3. Fix the credential provider secret for the alias password
4. Regenerate the P12 with matching key/store passwords (openssl pkcs12 -export default behavior)

Example fix

// before
quarkus.tls.my-cert.key-store.p12.alias-password=oldpass
// after
quarkus.tls.my-cert.key-store.p12.alias-password=keypass123

KeyStore ks = KeyStore.getInstance("PKCS12");
try (InputStream in = Files.newInputStream(Path.of("keystore.p12"))) {
    ks.load(in, storePassword);
}
ks.getKey(alias, aliasPassword.toCharArray()); // throws UnrecoverableKeyException early if wrong

try {
    tlsRegistry.get("my-cert");
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unable to recover the key")) {
        log.error("alias-password does not match the key entry; fix config or credential provider");
    }
}

When it happens

Trigger: verifyP12KeyStore with alias and alias-password configured; the alias-password in quarkus.tls.<name>.key-store.p12.alias-password (or from the credential provider) does not match the key's password in the P12.

Common situations: P12 whose key entry was created with a different password than the store password; stale alias-password after regenerating the keystore; credential provider returning the wrong secret; special characters/misquoted password in properties.

Related errors

• Alias ' ' not found in P12 key store (certificate not found)
• Alias ' ' not found in P12 key store (private key not found)
• Invalid P12 key store configuration for certificate
• Unable to load P12 store ' ', verify the password.
• Unable to verify alias

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

Appendix: source

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

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

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

    private static void verifyTrustStoreAlias(Optional<String> maybeAlias, String name, KeyStore ks) {
        if (maybeAlias.isPresent()) {
            String alias = maybeAlias.get();
            try {
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in P12 trust store (certificate not found)'" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in P12 trust store '" + name + "'", e);
            }
        }
    }

View on GitHub (pinned to e1c734241f)