apache/pulsar · error · IllegalArgumentException

certFilePath must not be null

Error message

certFilePath must not be null

What it means

The AuthenticationDataTls(String certFilePath, String keyFilePath) constructor throws IllegalArgumentException when certFilePath is null. TLS authentication data wraps the client certificate chain file for mTLS; without a certificate path the auth data cannot be built, so it fails fast.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/AuthenticationDataTls.java:53

import org.apache.pulsar.common.util.tls.PemReader;

@CustomLog
public class AuthenticationDataTls implements AuthenticationDataProvider {
    private static final long serialVersionUID = 1L;
    protected X509Certificate[] tlsCertificates;
    protected PrivateKey tlsPrivateKey;
    private transient FileModifiedTimeUpdater certFile, keyFile;
    // key and cert using stream
    private transient InputStream certStream, keyStream;
    @SuppressFBWarnings(value = "SE_TRANSIENT_FIELD_NOT_RESTORED",
            justification = "Using custom serializer which Findbugs can't detect")
    private transient Supplier<ByteArrayInputStream> certStreamProvider, keyStreamProvider, trustStoreStreamProvider;
    private static final Map<String, String> headers = Collections.singletonMap(
            PULSAR_AUTH_METHOD_NAME, AuthenticationTls.AUTH_METHOD_NAME);

    public AuthenticationDataTls(String certFilePath, String keyFilePath) throws KeyManagementException {
        if (certFilePath == null) {
            throw new IllegalArgumentException("certFilePath must not be null");
        }
        if (keyFilePath == null) {
            throw new IllegalArgumentException("keyFilePath must not be null");
        }
        this.certFile = new FileModifiedTimeUpdater(certFilePath);
        this.keyFile = new FileModifiedTimeUpdater(keyFilePath);
        this.tlsCertificates = PemReader.loadCertificatesFromPemFile(certFilePath);
        this.tlsPrivateKey = PemReader.loadPrivateKeyFromPemFile(keyFilePath);
    }

    public AuthenticationDataTls(Supplier<ByteArrayInputStream> certStreamProvider,
            Supplier<ByteArrayInputStream> keyStreamProvider) throws KeyManagementException {
        this(certStreamProvider, keyStreamProvider, null);
    }

    public AuthenticationDataTls(Supplier<ByteArrayInputStream> certStreamProvider,
            Supplier<ByteArrayInputStream> keyStreamProvider, Supplier<ByteArrayInputStream> trustStoreStreamProvider)
            throws KeyManagementException {

View on GitHub (pinned to 820761864e)

Solutions

1. Provide a valid PEM certificate chain path (AuthenticationTls 'tlsCertFile' auth param) to the constructor.
2. Verify the cert secret/volume is mounted and the path variable is populated before client startup.
3. Fail fast in app startup: check certFilePath != null before constructing the authentication data.

Example fix

// before
new AuthenticationDataTls(certFilePath, keyFilePath); // certFilePath is null
// after
Objects.requireNonNull(certFilePath, "tlsCertFile must be configured");
new AuthenticationDataTls(certFilePath, keyFilePath);

Objects.requireNonNull(certFilePath, "TLS cert file path (tlsCertFile) must be configured");
if (!new File(certFilePath).canRead()) throw new IllegalStateException("cert file not readable: " + certFilePath);

try {
    authData = new AuthenticationDataTls(certFilePath, keyFilePath);
} catch (IllegalArgumentException | KeyManagementException e) {
    log.error("TLS auth misconfigured: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Constructing AuthenticationDataTls with a null first argument, e.g. when AuthenticationTls is configured without the tlsCertFile parameter or the cert path variable was never assigned.

Common situations: authParams JSON missing the 'tlsCertFile' key; Kubernetes secret/volume mount for the cert absent so the path resolution yields null; programmatic client setup forgetting to set the certificate; environment-specific config dropping the TLS section.

Related errors

• keyFilePath must not be null
• Passed in parameter empty. KEYSTORE_PATH: ${keyStorePath} KE
• certStream provider or stream must not be null
• keyStream provider or stream must not be null
• cert/key file path or cert/key stream must be present

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