apache/pulsar · error · KeyStoreException

Failed to set the private key

Error message

Failed to set the private key

What it means

KeyStoreHolder.setPrivateKey() wraps any GeneralSecurityException thrown by KeyStore.setKeyEntry() in a KeyStoreException with the message "Failed to set the private key", with the original exception as cause. The entry is protected with the holder's internal entry password.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/util/KeyStoreHolder.java:107

     *         reachable.
     */
    public char[] getEntryPassword() {
        return Arrays.copyOf(entryPassword, entryPassword.length);
    }

    public void setCertificate(String alias, Certificate certificate) throws KeyStoreException {
        try {
            keyStore.setCertificateEntry(alias, certificate);
        } catch (GeneralSecurityException e) {
            throw new KeyStoreException("Failed to set the certificate", e);
        }
    }

    public void setPrivateKey(String alias, PrivateKey privateKey, Certificate[] certChain) throws KeyStoreException {
        try {
            keyStore.setKeyEntry(alias, privateKey, entryPassword, certChain);
        } catch (GeneralSecurityException e) {
            throw new KeyStoreException("Failed to set the private key", e);
        }
    }

}

View on GitHub (pinned to 820761864e)

Solutions

1. Read the cause to find the real reason (unrecoverable key, algorithm not supported, invalid key format).
2. Verify the PrivateKey matches the first certificate in the chain (compare public keys) before calling setPrivateKey.
3. Ensure the key is in a format supported by the store type/provider (PKCS8; convert with openssl if needed).
4. Confirm the holder was constructed successfully and the store is not in a failed state before adding key entries.

Example fix

// before
holder.setPrivateKey("broker", wrongKey, brokerChain); // key does not match chain
// after
if (!wrongKeyEqualsCert(wrongKey, brokerChain[0])) {
    throw new IllegalArgumentException("private key does not match certificate");
}
holder.setPrivateKey("broker", wrongKey, brokerChain);

static void requireKeyMatchesChain(PrivateKey key, Certificate[] chain) {
    if (key == null || chain == null || chain.length == 0) {
        throw new IllegalArgumentException("private key and non-empty chain required");
    }
    try {
        chain[0].verify(key.getPublic() instanceof PublicKey
                ? (PublicKey) key.getPublic() : chain[0].getPublicKey());
    } catch (Exception e) {
        throw new IllegalArgumentException("private key does not match certificate chain", e);
    }
}

try {
    holder.setPrivateKey(alias, privateKey, certChain);
} catch (KeyStoreException e) {
    // cause: key/chain mismatch, unsupported algorithm, provider restriction
    throw new RuntimeException("cannot store key '" + alias + "': " + e.getCause(), e);
}

When it happens

Trigger: Calling setPrivateKey(alias, privateKey, certChain) where the key/chain is rejected: null private key, cert chain mismatched with the key, key algorithm unsupported by the store type/provider (e.g. FIPS store rejecting certain key algorithms), or uninitialized store.

Common situations: Loading TLS client certs from PEM files where the private key does not match the certificate chain (wrong key/cert pair from separate files); RSA vs EC key issues under FIPS providers; corrupted PEM-to-PKCS8 conversion; provider-pinned stores enforcing algorithm restrictions.

Related errors

• Configured truststore 'trustStorePath' holds no X.509 certif
• KeyStore creation error
• Failed to set the certificate
• Issuer URL does not use https, but must:
• Failed to acquire TLS material for purpose ${purpose}

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/65426dd9135387b1. Report an issue: GitHub.