What causes "Certificate loading error" in apache/pulsar?

Verify the certificate file path exists and is readable by the process (ls -l, permissions, mount)

apache/pulsar · error · KeyManagementException

Certificate loading error

Error message

Certificate loading error

What it means

PemReader.loadCertificatesFromPemFile wraps any GeneralSecurityException or IOException raised while reading and parsing the PEM certificate file into a KeyManagementException with message 'Certificate loading error'. It signals that the certificate file could not be read or its PEM blocks could not be parsed as X.509 certificates.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/util/tls/PemReader.java:89

     * Load PEM certificates, manufacturing them with a pinned JCA provider.
     *
     * @param certFilePath the PEM file path
     * @param jcaProvider  the pinned JCA provider, or {@code null} for the JVM provider search order
     * @return the loaded certificates, or {@code null} when no path was given
     * @throws KeyManagementException if the certificates cannot be loaded
     */
    public static X509Certificate[] loadCertificatesFromPemFile(String certFilePath, Provider jcaProvider)
            throws KeyManagementException {
        X509Certificate[] certificates = null;

        if (certFilePath == null || certFilePath.isEmpty()) {
            return certificates;
        }

        try (FileInputStream input = new FileInputStream(certFilePath)) {
            certificates = loadCertificatesFromPemStream(input, jcaProvider);
        } catch (GeneralSecurityException | IOException e) {
            throw new KeyManagementException("Certificate loading error", e);
        }

        return certificates;
    }

    public static X509Certificate[] loadCertificatesFromPemStream(InputStream inStream) throws KeyManagementException  {
        return loadCertificatesFromPemStream(inStream, null);
    }

    /**
     * Load PEM certificates from a stream, manufacturing them with a pinned JCA provider.
     *
     * @param inStream    the PEM stream
     * @param jcaProvider the pinned JCA provider, or {@code null} for the JVM provider search order
     * @return the loaded certificates, or {@code null} when no stream was given
     * @throws KeyManagementException if the certificates cannot be loaded
     */
    public static X509Certificate[] loadCertificatesFromPemStream(InputStream inStream, Provider jcaProvider)

View on GitHub (pinned to 820761864e)

Solutions

Verify the certificate file path exists and is readable by the process (ls -l, permissions, mount)
Ensure the file contains valid PEM CERTIFICATE blocks (BEGIN/END lines, base64 intact, correct chain order)
Check the cause in the stack trace to distinguish I/O problems from parse/provider problems
Re-export the certificate in PEM (X.509) format, e.g. openssl x509 -in cert.der -out cert.pem

Example fix

// before
tlsCertificateFilePath=/secrets/broker.crt   // file not mounted
// after
// ensure the PEM file is present, e.g.:
// openssl x509 -in cert.der -out /secrets/broker.pem
// then in code, guard:
File f = new File(path);
if (!f.canRead()) throw new IllegalStateException("cert file missing: " + path);

Defensive patterns

Strategy: try-catch

Validate before calling

File f = new File(certPath);
if (!f.isFile() || !f.canRead()) throw new IllegalStateException("Unreadable cert file: " + certPath);
try (BufferedReader r = new BufferedReader(new FileReader(f))) { if (!"-----BEGIN CERTIFICATE-----".equals(r.readLine().trim())) throw new IllegalStateException("Not a PEM cert file"); }

Try / catch

try { return PemReader.loadCertificatesFromPemFile(path); } catch (KeyManagementException e) { log.error("Failed loading certificates from {}: {}", path, e.getCause()); throw new IllegalStateException("Invalid certificate configuration", e); }

Prevention

Validate file existence/readability before wiring the TLS config
Ensure the file contains proper BEGIN/END CERTIFICATE PEM blocks
Log e.getCause() to distinguish I/O vs parse vs provider errors
Convert DER/binary certs to PEM before use
Mount secrets and verify permissions in containerized deployments

When it happens

Trigger: Certificate file path does not exist / not readable (FileNotFoundException, wrapped IOException); invalid or corrupted PEM content; unsupported provider combination that fails during certificateFactory(...) (CertificateException); truncation or permission errors while reading the stream.

Common situations: Wrong tlsCertificateFilePath configured on broker/client; file missing after deployment or volume not mounted; PEM containing only a private key or encrypted PKCS#8 blocks the parser cannot handle; FIPS provider lacking X.509 CertificateFactory.

Understand the failure class

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

Related errors

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