Unclean leader election in Apache Kafka: when a partition may lose data to come back online
When every in-sync replica (ISR) of a partition is gone, the partition has no leader and producers and consumers for it are blocked. Unclean leader election is the setting that decides whether a replica outside the in-sync set may take leadership to bring the partition back. The price of saying yes is data loss, because that replica may lack records the old leader had acknowledged. Teams usually meet this decision during an outage, when a broker failure or a rack loss has taken down the only replicas that were current, and someone must choose between waiting and accepting missing data. The default keeps the behavior off through the topic-level unclean.leader.election.enable setting, which defaults to false, so a partition stays offline until a replica in the ISR returns.
Because the default favors consistency, the practical work happens before any incident. Decide per topic which data can tolerate loss, such as metrics or replayable telemetry, and which cannot, such as payment or ledger events. Record that choice in your topic provisioning standards, and make sure the setting is not enabled by a cluster-wide default that applies to every team. Confirm your replication factor and min.insync.replicas values against your failure domains, since the fewer replicas that stay current, the more often this decision arises. The Kafka topic configs reference lists the exact behavior for each option in the release you run.
On a KRaft cluster, changing the setting dynamically does not take effect immediately. The change waits for the periodic unclean election thread, which runs every 5 minutes by default, unless you trigger the election yourself with kafka-leader-election.sh and the unclean option. Treat any forced election as a logged, approved action: record the partition, the lost replicas, the offsets at risk and the person who approved the loss, and reset the setting to false afterward. The Kafka design documentation describes this as a deliberate trade between availability and consistency. Enable unclean election only for topics where a justified loss window is documented and accepted, and confirm the exact command options against your Kafka version before an incident.
Which unclean leader election setting fits which decision
This table compares the three ways a Kafka partition can end up electing an out-of-sync leader: the default topic setting, enabling it on a KRaft cluster, and forcing an election by hand. Read each row against the data-loss exposure in the middle column, and treat the right-hand column as the only situation where that option is worth the risk.
| Option | What it changes | Data-loss exposure and when it fits |
|---|---|---|
| unclean.leader.election.enable left at false (default) | A partition with no in-sync replica stays offline until a replica that was in sync returns. No out-of-sync replica can become leader. | No acknowledged records are lost to unclean election. The partition is unavailable for as long as the in-sync replicas stay down. Fits almost all production topics, especially those where losing acknowledged writes is unacceptable. |
| Topic set to true with a dynamic change in KRaft | Out-of-sync replicas become eligible for leader election. The change is applied by the periodic unclean election thread, which runs every 5 minutes by default, so it is not immediate. | Records written only to the old leader can be lost, and consumers may see offsets that rewind. Fits a topic where availability matters more than completeness, such as ephemeral telemetry or data that producers can safely replay. Confirm the timing in the Kafka 4.3 topic configuration reference. |
| Manual forced election with kafka-leader-election using the unclean option | Triggers a one-off election for selected partitions and promotes an out-of-sync replica now, without changing the topic setting for future failures. | Same loss exposure as enabling the setting, limited to the partitions you target and the moment you run it. Fits a documented recovery run-book after an incident, when you have confirmed the old leader cannot return and accepted the lost tail of data. |
Why the Kafka default keeps data over availability
The Kafka design documentation frames unclean leader election as a trade-off between availability and consistency. When a partition loses every replica in its in-sync replica set (ISR), Kafka can either wait for one of those replicas to return, which keeps committed records but leaves the partition unavailable, or elect a replica that was out of sync, which restores service but can discard writes the leader had already acknowledged. The default is `false`, so Kafka chooses to wait. That choice protects data first, and it is the reason a partition can stay offline during a broker outage until a replica from the ISR comes back. Changing it is a decision about which failure you prefer to explain to the business, not a performance tweak.
What can be lost depends on two things: the acknowledgment setting on producers (acks) and the composition of the ISR at the moment of failure. A write acknowledged with acks=all has reached every replica currently in the ISR, so a clean leader election from that set does not lose it. A write acknowledged after the leader alone persisted it may exist only on the old leader, and an out-of-sync replica that takes over will not have it. Settings such as min.insync.replicas and the replication factor determine how small the ISR can get before writes are refused. Before touching unclean.leader.election.enable, confirm these values for each topic that matters, because a platform that accepts writes with weak acknowledgments will lose data under any election policy.
Many teams should therefore review durability settings first and treat unclean election as a last resort that is rarely justified. Check the replication factor, min.insync.replicas, producer acks and the rack or site placement of replicas for every critical topic, and confirm with your own runbook which topics can tolerate loss and which cannot. The Kafka topic configuration reference describes the setting and its default, and it is the right document to check against the version you run. If a partition is stuck, the first step is to find which replicas are missing and bring them back, not to elect a stale one. Record who is authorized to make that call and under what conditions, because the trade-off is made during an incident, usually under pressure.
How teams decide between waiting and electing during an outage
Some topics hold data that the team can regenerate from a system of record, such as a change data capture stream that can be re-snapshotted or a cache feed that can be replayed from a database. For these topics, the cost of an unclean election is usually a bounded repair job, while the cost of waiting is a partition that stays unavailable for as long as the lost replicas stay down. Answer first: can the source be re-read for the affected window, how long would a rebuild take, and do downstream consumers tolerate duplicates or gaps during it?
- Source of record: Confirm which system can regenerate the records and that its history covers the offsets at risk.
- Consumer tolerance: Check whether consumers are idempotent and whether they can reset offsets safely.
- Rebuild effort: Estimate the re-ingestion work with the owners of the source, not from memory.
- Approver: Typically the owning platform lead, with the data owner informed.
- Evidence: Record the affected offsets, the election time and the rebuild plan.
Before the incident, confirm the rebuild path has been exercised, because a repair that has never run is an assumption rather than a plan.
Other topics hold events where a missing record changes the outcome downstream. Payment events, ledger postings, access logs and audit trails are typical examples. Here an unclean election can silently remove committed records, and consumers may already have acted on them. Answer first: which consumers have already processed the offsets that could be lost, and would a gap in the trail be detectable or acceptable to the auditor?
- Downstream effects: List the systems that consume the topic and whether they have acted on records beyond the high watermark.
- Retention obligations: Ask compliance owners what must be retained and whether a gap is reportable.
- Approver: Usually a senior owner in the data or risk function, with security and compliance sign-off.
- Evidence: Record the decision, the reasoning, the offsets lost and reconciliation results.
- Prevention review: Check whether the topic should use stronger replication settings so the choice is rarely forced.
For these topics, the decision should be made in advance and written down, because the incident owner may not have the authority or information to weigh the losses alone.
When a partition has no in-sync replica and the owner must choose, the decision is time-pressured and often made with partial information. Waiting keeps the log intact but leaves producers and consumers blocked. Electing an out-of-sync replica restores service but may discard records that were acknowledged to producers. Answer first: which replicas are alive, what their log end offsets are, whether the lost leader can return, and how long the business can tolerate the outage.
- Replica state: Check which brokers are down, their last known offsets and whether they can recover soon.
- Triage order: Identify which partitions matter most and whether the outage is isolated.
- Approver: The incident commander with the topic owner, following a pre-agreed escalation path.
- Forcing the election: Use
kafka-leader-election.shwith the unclean option only after the decision is recorded. - Evidence: Capture the timeline, the commands run, the offsets before and after, and the reconciliation owner.
After the incident, check that the topic configuration and runbook match the decision that was taken.
How to change unclean leader election safely in KRaft
This sequence lets a team decide whether a specific topic may elect an out-of-sync replica, apply that change with a recorded owner, verify it took effect and return the setting to false once the emergency has passed.
Confirm affected topics and current settings
Identify the partitions that have no available leader and the topics they belong to, then read the current value of unclean.leader.election.enable for each topic using the Kafka topic configuration tooling. Confirm whether the value is set at the topic level or inherited from the cluster default, which is false. Record the output in the incident or change ticket. The step is done when every affected topic has a recorded current value and the partitions without a leader are listed.
Record in-sync replica state for each partition
For each leaderless partition, capture the current leader, the replica set and the in-sync replica set from the topic description output. Note which brokers are offline, whether they have failed disks or lost logs, and whether any of them can be restarted with their data intact. Ask the platform team to confirm the broker status from the cluster itself, not only from monitoring. The step is done when the ISR state for each partition is written down and someone can explain why no in-sync replica is available.
Decide who may approve the change
Agree in writing who may approve enabling unclean leader election, normally the service owner for the data and a platform lead, and state which data loss the business accepts for those topics. Include the expected recovery path for the lost records, such as producer retries or reprocessing from a source system. Confirm that the approval names the topics and partitions, not the whole cluster. The step is done when the approval record names the approver, the topics and the accepted loss.
Apply the dynamic configuration change
Set unclean.leader.election.enable to true only on the approved topics, using a targeted topic configuration change rather than a cluster-wide default. Because the change is dynamic, the platform team should note the exact time it was applied. In KRaft, the setting is not evaluated immediately: the periodic unclean election thread checks for it, and the default interval is 5 minutes. If the team cannot wait for that interval, run the election tool with the unclean option for the affected partitions instead. The step is done when the change command has returned successfully and the time of application is logged.
Verify the election outcome
After the wait interval has passed, or after the forced election has run, describe the affected topics again and confirm that each partition now has a leader and that the leader is the expected broker. Check that the configuration shows true for the approved topics and that no other topics were changed. Confirm with the service owner that the consumers can read again and that the lost-record scope matches the approval. The step is done when every partition has a leader, the configuration matches the approval and the service owner has signed off the recovery.
Return the setting to false
Once the original broker or replica recovers and the partitions have rejoined the in-sync replica set, set unclean.leader.election.enable back to false on each topic that was changed. Remove the topic-level override if your process uses one, so the topic inherits the cluster default. Confirm the new value with the topic configuration output. The step is done when the value reads false on every changed topic and the change is recorded in the ticket.
Close the change record
Record the final topic settings, the time each change was applied and reverted, the partitions affected and the data loss, if any, identified during recovery. Pass the record to the team that owns the data so they can reconcile downstream systems. Keep the record with your change management evidence. The step is done when the record is complete and the reconciliation owner has acknowledged it.
Security and operational controls around a forced or unclean election
A forced or unclean election can cost committed data, so the decision to run one should be restricted, recorded and watched. The controls below connect Kafka authorization and authentication to change tracking, alerting, consumer behavior and post-election reconciliation.
Restrict who can change elections
Limit topic configuration changes and leader election to a small operator group through Kafka authorization. In KRaft clusters, ACLs live in the cluster metadata log, and resources without ACLs are limited to super users unless allow.everyone.if.no.acl.found is set to true. Confirm that setting is false or unset in your environment, then grant the alter and cluster-level permissions needed for elections only to named service principals. Authenticate those operators with SSL client certificates or one of the SASL mechanisms in the security overview, so every election is tied to an identifiable identity.
Require a ticket and approver
Treat unclean.leader.election.enable and any manual election as a change that needs a ticket, a named approver and a stated reason, such as an outage with no in-sync replica that will not recover. Record the before and after value of the config, the partition or topic affected, the operator identity and the time. Store this record outside the Kafka cluster so it survives a cluster failure. Review whether the setting was returned to false after the incident.
Alert on unclean elections
Create alerts for any unclean leader election and for partitions that are offline or have no leader. Route them to the on-call team that owns the topic, not only to the platform team. The alert should fire even when the election was intentional, because an intentional election still means records may have been lost. Check the broker metrics your monitoring stack already collects, and confirm the metric names against the Kafka version you run before you build dashboards.
Runbooks for consumers
Consumers must tolerate offsets that move backward or records that never arrive. Write a runbook for each consumer group that covers how to detect a rewind, which downstream tables or caches need rebuilding, and who decides whether to reprocess a range. Idempotent writes and keyed upserts make replay safer. Test the runbook against a non-production cluster before the first real incident, using a deliberately forced election.
Reconcile data after the election
After an unclean election, compare the producer's source of truth with what the topic now holds. Identify the offset range that was on the old leader but not on the new one, then decide whether producers should resend from their own logs, whether a database or event source must be replayed, or whether the loss is accepted and documented. Keep producer-side logs or upstream change logs long enough to cover the gap, and record the reconciliation result against the incident ticket.
Use Kafka authentication for the audit trail
Audit evidence is only as strong as the identity behind each action. Use TLS client authentication or a SASL mechanism for every operator and automation account, and avoid shared credentials for admin tools. The security overview describes SSL and SASL options, including SCRAM and OAUTHBEARER, that you can match to your identity provider. Confirm which mechanism your admin tooling supports before you standardize on one, and keep the mapping from each principal to a named person current.
Questions teams ask before changing unclean leader election
Is unclean leader election ever justified in production?
Yes, but only for a narrow set of topics where keeping the partition writable matters more than keeping every acknowledged record. The Kafka design documentation describes this as a trade-off: waiting for an in-sync replica preserves data but leaves the partition unavailable until one returns. When only lagging replicas survive, electing one of them lets producers and consumers resume, but records the old leader accepted and the new leader never received are lost, and consumers may see offsets move backward. Teams usually justify the setting for telemetry or cache-like streams where gaps are tolerable and the source can be replayed. It is rarely justified for payments, ledgers or events that trigger irreversible actions. Write the justification down before any change, and name the person who accepted the loss risk.
Should we enable unclean leader election for the whole cluster?
Usually no. The default is false, and a cluster-wide enablement exposes every topic to the loss trade-off, including topics that carry data your teams cannot regenerate. A safer pattern is to keep the default off and enable the setting only on named topics whose owners have accepted the risk in writing. Start by inventorying topics by criticality and marking which ones can tolerate gaps and replay from a source system. Cost and effort rise with the number of overrides, because each one needs a record, an owner, a monitoring rule and a review date. A cluster with a few well-understood topics is far easier to govern than a shared platform with many teams. Before you write the runbook, confirm in the topic configuration reference how your Kafka version scopes the setting, since broker-level defaults and per-topic values interact.
How long does a change to unclean leader election take to apply in KRaft?
In KRaft mode, a dynamic change does not take effect immediately. It waits for the periodic unclean election thread, which runs every 5 minutes by default, so expect a delay of up to that interval. Plan the change window with that wait in mind, and verify the effective value on each affected topic after the change. Do not assume the change applied because the command returned without error. Monitor partition leadership and offline partition indicators during the window so the team can tell a normal wait from a real outage. If you need an election sooner, the next question covers the tooling option. Record the change time, the verification output and the approver in your change ticket so the audit trail matches what happened.
Can we force a leader election without enabling unclean leader election?
Yes. The Kafka tooling can trigger an election with the unclean option through kafka-leader-election.sh, which lets an operator act on specific partitions without changing the topic setting. The configuration can stay false while one partition is recovered under a deliberate, logged action. This is still an unclean election, so the same data loss risk applies to that partition at that moment. Use it only after the team confirms that no in-sync replica will return within the acceptable outage window, and capture the partition list, the replica state and the approving operator. Confirm the exact flags for your Kafka version in the 4.3 documentation, and rehearse the command on a non-production cluster first. Leaving the setting enabled afterward is not required for the recovery.
What effort does the decision and runbook need?
The effort splits into a one-time design phase and a recurring operating phase. One-time work includes inventorying topics, classifying them, agreeing risk acceptance with data owners, writing the forced-election runbook and rehearsing it. Recurring work includes reviewing overrides, checking that new topics inherit the intended default, and repeating the rehearsal after Kafka upgrades. The main drivers are the number of topics that need a decision, how many consumers must recover correctly after lost records (through idempotent processing, replay or reconciliation jobs), how many teams share the cluster, and how strict the audit evidence must be. No duration is given here. Ask any partner for an estimate tied to a written scope, and size your own topic inventory first, because it determines most of the rest.
Can an internal team own unclean leader election decisions and runbooks?
Yes, if the team already runs Kafka with on-call coverage, change control and monitoring for partition availability. The skill to build is judgment about data loss as well as command syntax. Assign one owner for the policy, one owner for each cluster's runbook, and a named approver from the data owner side. Internal teams often underestimate the consumer side, where application teams must agree how to handle gaps and rewound offsets, and the evidence work that continues after the first change. Test the runbook on a staging cluster that mirrors topic settings, and confirm that someone other than the runbook author can complete an election drill. A partner can help with design and testing, but policy decisions and risk acceptance stay with your organization.
What do we need to provide before a partner scopes this work?
A partner needs your topic inventory with owners, replication settings and minimum in-sync replica values, plus the criticality of each data flow. It also needs current monitoring and alerting coverage, the consumer applications that read each topic and whether they handle duplicates and gaps safely, and any audit requirements that touch availability or data integrity. Provide access to a non-production cluster on the same Kafka version, the change approval chain and the on-call model. With these inputs, the written scope can name the topics in scope, the runbooks to write, the tests to run and the sign-off points. DeployOpen agrees scope, deliverables and timelines in writing before work starts, so gaps in these inputs usually appear later as scope changes. Expect the quote to rise with the number of topics and consumer applications that need review.
What to confirm for your Kafka version and topics
Unclean leader election changes what a partition does when no in-sync replica is left, and the exact behavior depends on the Kafka version and the topics you run. The cards below are items to verify in your own environment before you change the setting or plan a forced election.
Dynamic change and forced election behavior
Confirm how your Kafka version handles a dynamic change to unclean.leader.election.enable. In KRaft mode, the change waits for the periodic unclean election thread unless you run the election tool with the unclean option. Test this on a non-production cluster running the same version, and record how long the change takes to apply. Confirm the exact command syntax for your release before you write any runbook that depends on it.
Interaction with replication and ELR settings
Check how unclean election combines with min.insync.replicas, acks settings and eligible leader replicas on your release. The eligible leader replicas behavior is covered on a separate page, so read it before you finalize a replication policy. Verify which setting protects a partition in your topology, because enabling unclean election alone does not define the outcome when the in-sync set shrinks.
Whether data can be rebuilt elsewhere
For each topic, confirm whether its records exist in another system, such as a source database, an upstream producer that can replay, or a mirrored cluster. Topics that can be reproduced from a source tolerate a truncated log better than topics that are the system of record. Document the replay window and the owner who approves the trade-off, since an unclean election can discard acknowledged records that were not yet replicated.
Supported release lines and upgrade status
Check the Kafka downloads page for the release lines currently supported and the bugfix status of the version you run. Election behavior and tooling can change between releases, so a runbook written for one line may not match another. Confirm that your version is in a supported line before you rely on documented behavior, and plan any upgrade so the election procedure is retested on the target version.
Detection by your monitoring
Confirm that your monitoring can detect an unclean leader election when it happens. Check whether your metrics stack exposes the broker and controller signals you need, and whether an alert reaches the on-call team with enough context to decide whether to accept data loss. Test the alert by simulating a partition with no in-sync replicas in a staging environment, and verify that the runbook names an owner for the decision.
How DeployOpen scopes and delivers Kafka leader election decisions
DeployOpen treats the unclean leader election setting as a documented, written decision for each Kafka topic group, not a default to accept or flip. We plan the availability and data loss trade-off with your owners, then implement, test and hand over the configuration and runbook for your self-hosted cluster.
How we scope
- Engagements are fixed-scope, with the written scope agreed before any work starts.
- The scope lists which topics and partitions are in play and who owns the availability and data loss decision.
- We record which workloads can tolerate data loss and which must wait for an in-sync replica to return.
How we build
- We set unclean.leader.election.enable explicitly per topic group, and confirm the cluster-wide default on your brokers.
- We test a dynamic change on a non-production KRaft cluster, including the periodic election thread delay.
- We rehearse a forced election with kafka-leader-election on a staging partition before any production use.
How we hand over
- You receive the written decision record, configuration state and a runbook for when every in-sync replica is gone.
- The runbook covers how to confirm which replicas are in sync and who approves an emergency election.
- We document how to reverse the setting once the cluster has recovered its in-sync replicas.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- We can review the setting again when topic ownership, replication factor or Kafka version changes.
- Retainer scope and response expectations are agreed in writing, and confirmed with you before work starts.

