apache/pulsar · error · KeyStoreException

Failed to set the certificate

Error message

Failed to set the certificate

What it means

KeyStoreHolder.setCertificate() wraps any GeneralSecurityException thrown by KeyStore.setCertificateEntry() in a KeyStoreException with the message "Failed to set the certificate", keeping the original as cause. This stores a trusted certificate entry under the given alias in the in-memory store.

Source

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

        return keyStore;
    }

    /**
     * @return the password this holder's key entries are stored under; a {@code KeyManagerFactory} reading
     *         them must be initialized with it. A fresh copy is returned on each call and is owned by the
     *         caller, who should zero it once the factory has consumed it (as
     *         {@code JdkSslContexts.setupKeyManager} does) rather than leaving the plaintext password
     *         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. Inspect the cause (e.g. KeyStoreException 'Cannot overwrite own certificate' or 'key entry with alias ...') to determine the conflict.
2. Use a unique alias per certificate; if the alias is taken by a key entry, delete it first (keyStore.deleteEntry(alias)) or pick a different alias.
3. Verify the Certificate object is non-null and was parsed successfully before adding it.
4. Check that the store type/provider in use supports trusted certificate entries.

Example fix

// before
holder.setCertificate("server", caCert); // fails if "server" already holds a key entry
// after
holder.setPrivateKey("server", key, chain);
holder.setCertificate("server-ca", caCert); // distinct alias

static void requireAddable(KeyStoreHolder holder, String alias, Certificate cert) throws GeneralSecurityException {
    Objects.requireNonNull(cert, "certificate must not be null");
    if (holder.getKeyStore().isKeyEntry(alias)) {
        throw new IllegalArgumentException("alias already holds a key entry: " + alias);
    }
}

try {
    holder.setCertificate(alias, cert);
} catch (KeyStoreException e) {
    // cause: alias conflict, null/invalid cert, or provider restriction
    throw new RuntimeException("cannot add trusted cert '" + alias + "': " + e.getCause(), e);
}

When it happens

Trigger: Calling setCertificate(alias, cert) where the store rejects the entry: alias already holds a key entry, null certificate, or the underlying store type/provider refuses trusted-cert entries.

Common situations: Building a TrustManagerFactory trust store from PEM files where the same alias is reused for a private key and then a certificate (or vice versa); passing an invalid/corrupt Certificate object produced by an earlier failed parse; provider-restricted (FIPS) stores.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Configured truststore 'trustStorePath' holds no X.509 certif
• KeyStore creation error
• Failed to set the private key
• Issuer URL does not use https, but must:
• Failed to get TLS certificates from client

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