skip to content

How do you manually trigger preferred leader election with kafka-leader-election.sh, and how does PREFERRED differ from UNCLEAN election?

level: middleimportance: should knowfreq 45%

answer

  1. kafka-leader-election.sh --election-type PREFERRED
  2. Replaces kafka-preferred-replica-election.sh
  3. PREFERRED = ISR-only, lossless
  4. UNCLEAN = out-of-sync, may lose data
  5. --all-topic-partitions | --topic/--partition | --path-to-json-file

basics

~10 s

Run kafka-leader-election.sh with --election-type PREFERRED to move leadership back to preferred replicas. PREFERRED only elects in-sync replicas (safe). UNCLEAN can elect an out-of-sync replica to restore availability, risking data loss.

solid answer

~40 s

kafka-leader-election.sh is the modern CLI (replacing the old kafka-preferred-replica-election.sh) that triggers leader elections on demand. You pass --bootstrap-server, --election-type PREFERRED or UNCLEAN, and either --all-topic-partitions, --topic + --partition, or --path-to-json-file listing specific partitions. PREFERRED moves each partition's leadership to the first replica in its AR list, but only if that replica is in the ISR — it is safe and lossless. UNCLEAN is the emergency option: when no in-sync replica is available, it elects an out-of-sync replica to bring the partition back online, which can discard records the old leader had but the new one didn't. You'd run PREFERRED after a rolling restart to re-balance load, and UNCLEAN only as a last-resort recovery when accepting data loss is better than an offline partition.

go deeper

for a junior

Know the command name and that --election-type PREFERRED rebalances leadership.

for a middle

Distinguish PREFERRED (safe, ISR-only) from UNCLEAN (lossy, last resort) and how to scope partitions.

for a senior

Operationalize it: scoping with JSON, staggering, and when to use it vs auto-rebalance.

for a principal

Set policy on unclean election and recovery runbooks balancing availability vs durability.

## The tool `kafka-leader-election.sh` (in Kafka's bin/) triggers leader elections from the command line. It superseded the older `kafka-preferred-replica-election.sh`. It talks to the cluster via `--bootstrap-server`. ### Selecting partitions (one of) - `--all-topic-partitions` — every partition in the cluster. - `--topic <name> --partition <n>` — a single partition. - `--path-to-json-file <file>` — a JSON file listing specific {topic, partition} pairs, useful to scope the blast radius. ### Election types - `--election-type PREFERRED`: move leadership to the **preferred replica** (first in AR) for each selected partition, **only if it is in the ISR**. Partitions already led by their preferred replica are skipped. This is the normal, safe way to re-balance leadership after restarts when `auto.leader.rebalance.enable=false`, or to force it immediately rather than waiting for the periodic check. - `--election-type UNCLEAN`: elect a replica that is **not in the ISR** when no in-sync replica can be leader. This restores availability but can **lose data**, because the elected replica may be missing the latest records that the previous leader acknowledged. ## PREFERRED vs UNCLEAN — the key contrast | | PREFERRED | UNCLEAN | |---|---|---| | Goal | Balance load | Restore availability | | Eligible replica | Must be in ISR | Can be out-of-sync | | Data loss risk | None | Possible | | When | Routine / scheduled | Emergency last resort | UNCLEAN election from the CLI is related to but distinct from the broker/topic config `unclean.leader.election.enable`. The config governs whether the controller will *automatically* pick an out-of-sync replica when a partition has no in-sync leader; the CLI lets an operator request it explicitly. ## Practical notes - Elections are asynchronous; the command requests them and reports per-partition success/failure (a PREFERRED election on a partition whose preferred replica is out-of-sync will fail/skip). - Each elected partition is briefly unavailable during transfer and clients must refresh metadata, so scope large clusters with a JSON file and stagger if needed. - PREFERRED election never moves data or changes the AR; only leadership changes.

  • Why would a PREFERRED election skip some partitions?
    Because the preferred replica isn't in the ISR for those partitions (so electing it would be unsafe), or the partition is already led by its preferred replica.
  • How does UNCLEAN election relate to unclean.leader.election.enable?
    The config controls whether the controller automatically elects an out-of-sync replica when no ISR leader exists; the CLI's UNCLEAN type lets an operator force that election manually as a recovery action.

saying these in an interview costs you the question

  • Claiming PREFERRED election can cause data loss — it only elects in-sync replicas.
  • Using the deprecated kafka-preferred-replica-election.sh as the current answer without noting the replacement.
  • Saying UNCLEAN is a normal/routine balancing tool.

context

resolving links…