apache/pulsar · error · IllegalArgumentException

keyFilePath must not be null

Error message

keyFilePath must not be null

What it means

The AuthenticationDataTls(String certFilePath, String keyFilePath) constructor throws IllegalArgumentException when keyFilePath is null. TLS authentication needs both the client certificate chain and the private key; a null key path means no private key can be loaded, so the constructor rejects it before any file I/O.

Source

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

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 {
        if (certStreamProvider == null || certStreamProvider.get() == null) {
            throw new IllegalArgumentException("certStream provider or stream must not be null");
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Provide the PEM private key path (AuthenticationTls 'tlsKeyFile' auth param) to the constructor.
2. Check the exact authParams key names — 'tlsCertFile' and 'tlsKeyFile' — for typos.
3. Validate both paths non-null before constructing the authentication data at startup.

Example fix

// before
params: {"tlsCertFile": "/certs/client-cert.pem"} // tlsKeyFile missing -> null
// after
params: {"tlsCertFile": "/certs/client-cert.pem", "tlsKeyFile": "/certs/client-key.pem"}

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

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 second argument, e.g. AuthenticationTls configured without the tlsKeyFile auth parameter, or a key path variable left unassigned.

Common situations: authParams JSON missing 'tlsKeyFile'; private key mounted under a different name than expected; splitting cert/key config across files where only the cert section was migrated; typo'd key name ('tlsKeyfile') silently yielding null.

Related errors

• certFilePath 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/3a7e087144147ff4. Report an issue: GitHub.