apache/kafka · error · ConfigException

SASL reconfiguration failed due to ${e}

Error message

SASL reconfiguration failed due to ${e}

What it means

Thrown by SaslChannelBuilder.validateReconfiguration as a ConfigException wrapping the IllegalStateException raised by SslFactory.validateReconfiguration. It only applies to a SASL_SSL listener being dynamically reconfigured (via the AlterConfigs / incremental AlterConfigs API). The library throws because the new SSL settings cannot be applied to the existing listener's SslFactory — typically because the keystore/truststore is missing, the alias is unchanged-but-required, or the factory was never fully initialized.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/network/SaslChannelBuilder.java:198

            }
        } catch (Throwable e) {
            close();
            throw new KafkaException(e);
        }
    }

    @Override
    public Set<String> reconfigurableConfigs() {
        return securityProtocol == SecurityProtocol.SASL_SSL ? SslConfigs.RECONFIGURABLE_CONFIGS : Set.of();
    }

    @Override
    public void validateReconfiguration(Map<String, ?> configs) throws ConfigException {
        if (this.securityProtocol == SecurityProtocol.SASL_SSL)
            try {
                sslFactory.validateReconfiguration(configs);
            } catch (IllegalStateException e) {
                throw new ConfigException("SASL reconfiguration failed due to " + e);
            }
    }

    @Override
    public void reconfigure(Map<String, ?> configs) {
        if (this.securityProtocol == SecurityProtocol.SASL_SSL)
            sslFactory.reconfigure(configs);
    }

    @Override
    public ListenerName listenerName() {
        return listenerName;
    }

    @Override
    public KafkaChannel buildChannel(String id, SelectionKey key, int maxReceiveSize,
                                     MemoryPool memoryPool, ChannelMetadataRegistry metadataRegistry) throws KafkaException {
        TransportLayer transportLayer = null;

View on GitHub (pinned to c31c9215e1)

Solutions

1. Verify the new ssl.keystore.location / ssl.truststore.location paths are readable by the broker process and the file format matches ssl.keystore.type.
2. Ensure ssl.keystore.password / ssl.key.password are also being updated (or already correct) in the same AlterConfigs request.
3. If the underlying cause is 'SslEngineBuilder has not been initialized', establish a connection on the listener first or restart the broker after the change instead of relying on dynamic reconfiguration.
4. Read the wrapped IllegalStateException message (the '${e}') in the broker log for the precise missing field.

Example fix

# before: only keystore path supplied -> IllegalStateException
ssl.keystore.location=/new/store.p12

# after: supply path + password + type together
ssl.keystore.location=/new/store.p12
ssl.keystore.password=*****
ssl.keystore.type=PKCS12

// Pre-flight: only attempt SSL reconfiguration with valid keystore/truststore paths.
Map<String, Object> newSslConfigs = /* ... */;
if (newSslConfigs.containsKey(SslConfigs.SSL_KEYSTORE_LOCATION_CONFIG)) {
    Path ks = Path.of((String) newSslConfigs.get(SslConfigs.SSL_KEYSTORE_LOCATION_CONFIG));
    if (!Files.isReadable(ks)) throw new ConfigException("keystore not readable: " + ks);
}
channelBuilder.validateReconfiguration(newSslConfigs);

try {
    channelBuilder.validateReconfiguration(newConfigs);
    channelBuilder.reconfigure(newConfigs);
} catch (ConfigException e) {
    // IllegalStateException from SslFactory was wrapped; keep the OLD ssl context.
    log.error("SASL/SSL reconfiguration rejected; retaining previous config", e);
    alertOperators(e);
}

When it happens

Trigger: Issuing an AlterConfigs / kafka-configs --alter on a broker to update ssl.keystore.location / ssl.truststore.location / related SSL props on a SASL_SSL listener, when SslFactory.validateReconfiguration detects the new config is incompatible with the current engine (e.g. keystore file not found, password unset, or keystore type unchanged with no key).

Common situations: Rotating broker certificates via dynamic config and pointing ssl.keystore.location to a path the broker can't read; changing only the keystore path without updating its password; using AlterConfigs on a listener whose SSL engine hasn't been created (no connections yet).

Related errors

• When the security.protocol configuration enables SASL, mecha
• Failed to create new KafkaAdminClient
• `mode` must be non-null if `securityProtocol` is `${security
• Type ${principalBuilderClass.getName()} is not an instance o
• Invalid url in bootstrap.servers: {url}

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/72d77fb43338eb9b.json. Report an issue: GitHub.