apache/pulsar · error · IllegalArgumentException

at least one key name must be configured

Error message

at least one key name must be configured

What it means

ProducerEncryptionPolicy requires at least one encryption key name. The producer-side encryption policy wraps messages with one of the configured public keys, so an empty keyNames list makes encryption impossible; the constructor validates this and throws IllegalArgumentException after checking keyNames is non-null.

Source

Thrown at pulsar-client-api-v5/src/main/java/org/apache/pulsar/client/api/v5/config/ProducerEncryptionPolicy.java:48

 *
 * <p>Construct via {@link #builder()}. Required: a {@link PublicKeyProvider} and at
 * least one key name.
 */
@EqualsAndHashCode
@ToString
public final class ProducerEncryptionPolicy {

    private final PublicKeyProvider publicKeyProvider;
    private final List<String> keyNames;
    private final ProducerCryptoFailureAction failureAction;

    private ProducerEncryptionPolicy(PublicKeyProvider publicKeyProvider,
                                     List<String> keyNames,
                                     ProducerCryptoFailureAction failureAction) {
        Objects.requireNonNull(publicKeyProvider, "publicKeyProvider must not be null");
        Objects.requireNonNull(keyNames, "keyNames must not be null");
        if (keyNames.isEmpty()) {
            throw new IllegalArgumentException("at least one key name must be configured");
        }
        Objects.requireNonNull(failureAction, "failureAction must not be null");
        this.publicKeyProvider = publicKeyProvider;
        this.keyNames = List.copyOf(keyNames);
        this.failureAction = failureAction;
    }

    /**
     * @return the provider used to load public keys for encryption
     */
    public PublicKeyProvider publicKeyProvider() {
        return publicKeyProvider;
    }

    /**
     * @return the configured key names; the producer encrypts each message's data
     *         key with every public key listed here
     */

View on GitHub (pinned to 820761864e)

Solutions

1. Add at least one key: .addKeyName("my-encryption-key") (or .keyNames(List.of("key1"))) on the builder before build()
2. Verify the broker cluster actually has the corresponding public key loaded via the admin API
3. Check the config source supplying the key names and fail earlier with a clearer message if it is empty

Example fix

// before
ProducerEncryptionPolicy p = ProducerEncryptionPolicy.builder()
        .publicKeyProvider(provider)
        .failureAction(ProducerCryptoFailureAction.FAIL)
        .build();
// after
ProducerEncryptionPolicy p = ProducerEncryptionPolicy.builder()
        .publicKeyProvider(provider)
        .addKeyName("my-encryption-key")
        .failureAction(ProducerCryptoFailureAction.FAIL)
        .build();

List<String> keyNames = config.getEncryptionKeyNames();
if (keyNames == null || keyNames.isEmpty()) {
    throw new IllegalArgumentException("producerEncryptionPolicy requires at least one encryption key name");
}

boolean hasKeyNames(List<String> l) { return l != null && !l.isEmpty(); }

try {
    policy = ProducerEncryptionPolicy.builder()...build();
} catch (IllegalArgumentException e) {
    log.error("Producer encryption policy invalid: {}", e.getMessage());
    throw new IllegalStateException("Fix encryption key configuration", e);
}

When it happens

Trigger: Calling ProducerEncryptionPolicy.builder().build() (or the private constructor) with keyNames never set, set to List.of() / Collections.emptyList(), or an explicitly empty list passed to the builder.

Common situations: Reading key names from config where the encryption.keys property is empty or missing; programmatically building the list from a filtered collection that ended up empty.

Related errors

• timeout must not be null
• timeout must not be negative
• privateKeyProvider must be set when failureAction is FAIL
• timeout must be > 0
• This version of pulsar-client supports only file:// encrypti

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