Kafka topic configuration: unclean leader election

Kafka unclean leader election explained: when all ISRs go offline, unclean.leader.election.enable promotes an out-of-sync replica — the risks and when to use.

Learn about unclean leader election and the availability vs durability trade-off

When no in-sync replicas (ISRs) are available, Kafka has to decide between staying unavailable or promoting an out-of-sync replica to leader. The unclean.leader.election.enable configuration controls this critical trade-off.

What you'll learn:

  • What unclean leader election means
  • When unclean elections cause data loss
  • Use cases where enabling this setting makes sense
  • How to configure unclean leader election

Clean vs unclean leader election

When the leader for a partition becomes unavailable, one of the in-sync replicas (ISR) becomes the new leader. This is a "clean" election because committed data exists on all ISRs by definition.

But what happens when no ISR exists except for the failed leader?

When the leader fails and no ISR is available, the outcome depends on unclean.leader.election:

When a leader fails with no ISR available, the false default waits for an ISR (data safe, availability impacted) while true promotes an out-of-sync replica (available immediately, potential data loss)

OptionBehaviorRisk
Wait for ISR (default)Topic unavailable until ISR recoversAvailability loss
Unclean electionPromote out-of-sync replicaData loss

The availability vs durability trade-off

If we allow out-of-sync replicas to become leaders, we will have data loss and data inconsistencies. If we don't allow them to become leaders, we face lower availability as we have to wait for the original leader to become available before the partition is back online.

Dangerous setting

Unclean leader election can cause permanent data loss. Understand the implications fully before enabling it. The default value of false is recommended for most use cases.

When to enable unclean leader election

Decision tree for unclean leader election: keep it disabled unless data loss is acceptable and availability is critical; enable it for metrics collection, log aggregation, and non-critical events, but keep it disabled for financial transactions, order processing, and audit logs

Use caseRecommendationReason
Financial transactionsDisableData loss unacceptable
Metrics/logsConsider enablingAvailability more important
Event streamingDepends on criticalityEvaluate trade-off
Audit complianceDisableRegulatory requirements
For an in-depth analysis, see Kafka at Datadog: Unclean Leader Elections.

Configure unclean leader election

Enable for a specific topic

kafka-configs --bootstrap-server localhost:9092 --alter \
  --entity-type topics --entity-name configured-topic \
  --add-config unclean.leader.election.enable=true

Disable (restore default)

kafka-configs --bootstrap-server localhost:9092 --alter \
  --entity-type topics --entity-name configured-topic \
  --delete-config unclean.leader.election.enable

Verify configuration

kafka-configs --bootstrap-server localhost:9092 --describe \
  --entity-type topics --entity-name configured-topic

Configure unclean leader election per topic rather than cluster-wide. This lets you enable it only for topics where availability is more important than durability.

See it in practice with Conduktor

Conduktor Console displays topic configurations including unclean leader election status. Monitor ISR counts and leader distribution to understand your replication health.

Next steps