quarkusio/quarkus · error · java.lang.IllegalArgumentException

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

Error message

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

What it means

The private key under the configured alias exists but cannot be recovered with the provided alias password: KeyStore.getKey threw UnrecoverableKeyException. The registry surfaces this as IllegalArgumentException including the keystore name and alias.

Source

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

            try {
                if (ks.getCertificate(alias) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in key store (certificate not found) '" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in key store '" + name + "'", e);
            }

            char[] ap = aliasPassword != null ? aliasPassword.toCharArray() : null;
            try {
                if (ks.getKey(alias, ap) == null) {
                    throw new IllegalStateException(
                            "Alias '" + alias + "' not found in key store (private key not found) '" + name + "'");
                }
            } catch (KeyStoreException | NoSuchAlgorithmException e) {
                throw new IllegalStateException("Unable to verify alias '" + alias + "' in key store '" + name + "'", e);
            } catch (UnrecoverableKeyException e) {
                throw new IllegalArgumentException(
                        "Unable to recover the key for alias '" + alias + "' in 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 trust store (certificate not found) '" + name + "'");
                }
            } catch (KeyStoreException e) {
                throw new IllegalStateException(
                        "Unable to verify alias '" + alias + "' in trust store '" + name + "'", e);
            }
        }

View on GitHub (pinned to e1c734241f)

Solutions

Set quarkus.tls.<name>.key-store.alias-password (or the credential provider reference) to the password protecting that specific key entry
If the key entry uses the same password as the store, ensure alias-password is correct or omitted and the store password is right
Re-export/rebuild the key store so the key is protected with a known password: keytool -keypasswd -alias <alias>
Verify the credential provider actually resolves the expected secret (check provider config and secret name)

Example fix

// before: key entry protected with a different password than the store
quarkus.tls.my-tls.key-store.p12.password=storepass
// after
quarkus.tls.my-tls.key-store.p12.password=storepass
quarkus.tls.my-tls.key-store.alias-password=keypass

Defensive patterns

Strategy: validation

Validate before calling

String aliasPassword = resolveAliasPassword(); // from config or provider
try {
    Key k = ks.getKey(alias, aliasPassword == null ? null : aliasPassword.toCharArray());
} catch (UnrecoverableKeyException e) {
    throw new IllegalArgumentException("Wrong alias-password for alias '" + alias + "'", e);
}

Try / catch

try {
    // init TLS
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to recover the key for alias")) {
        log.error("Set quarkus.tls.<name>.key-store.alias-password to the key entry password");
    }
    throw e;
}

Prevention

Always set alias-password when key entries are protected with a different password than the store
Use keytool -keypasswd to align key and store passwords and document one password policy
Fetch secrets via credential providers instead of raw env vars to avoid quoting/expansion issues
Rotate passwords in keystore and config together in the same deployment

When it happens

Trigger: Configured alias-password (or the credential-provider-supplied alias password) does not match the password used to protect that key entry; verifyKeyStoreAlias catches UnrecoverableKeyException.

Common situations: Key entry password differs from the key store password and alias-password was not set; stale/rotated credentials; special characters in the password mangled by env-var/property expansion; wrong credential provider chain picking an unrelated secret.

Related errors

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