Kafka: Error while fetching metadata — LEADER_NOT_AVAILABLE

Common symptoms

You may never see the exact string LEADER_NOT_AVAILABLE in your own logs and still have this exact problem — it often surfaces as one of these instead:

• Producer send() calls never complete, or retry forever without erroring out
• Consumers subscribe without error but never receive any records
• Client logs show repeated metadata refreshes that never make progress
• The initial connection succeeds, but every actual produce or fetch request hangs or times out
• A Kafka UI (Kafka UI, Conduktor, AKHQ) reports every broker as healthy while clients still can't send or receive

The exact error string

WARN [Consumer clientId=consumer-1, groupId=orders] Error while fetching metadata
with correlation id 7 : {orders=LEADER_NOT_AVAILABLE}

Every partition has exactly one leader replica; all reads and writes for that partition go through it. This message means the broker responded to a metadata request saying the orders topic's partition has no leader right now. It's a WARN, not a fatal exception, because Kafka clients automatically refresh metadata and retry on LEADER_NOT_AVAILABLE — leader elections are an expected, routine part of normal cluster operation, not evidence that something is broken by default. Whether that retry ever succeeds is what determines whether you have a real problem.

The benign case: right after topic creation

Creating a topic and electing a leader for each of its partitions are not instantaneous, and there's a small window between the topic existing and its leadership being fully propagated across the cluster. A produce or fetch request that lands in that window sees LEADER_NOT_AVAILABLE, and the client's built-in retry logic succeeds moments later once election finishes:

kafka-topics.sh --bootstrap-server localhost:9092 --create --topic orders --partitions 3

# a client sending immediately afterward may log ONE instance of:
# WARN ... Error while fetching metadata with correlation id 7 : {orders=LEADER_NOT_AVAILABLE}
#
# followed within a second or two by successful sends — no action needed

The signature that tells you this is the benign case: it appears once (or a handful of times) immediately after topic creation, then stops. If that's what you're seeing, there is nothing to fix.

This same race can show up even if you never ran --create yourself: with auto.create.topics.enable=true (the broker default in many setups), producing to a topic that doesn't exist yet creates it on the fly, and the very first request can land in the same just-in-time election window. It's mechanically identical to the case above — it just reads as "I never created a topic and got this error" instead.

If this window is a nuisance on a slow-electing cluster, the client-side metadata.max.age.ms setting controls how often the client proactively refreshes its metadata; lowering it shortens how long the client can keep using stale metadata before it learns a leader now exists.

Fix 1: if it repeats forever, check advertised.listeners

This is the dominant cause when the warning never resolves — especially in Docker or Kubernetes. The mechanism is subtle enough to be worth walking through carefully, because the symptom (bootstrap succeeds, everything after fails) is genuinely confusing the first time you hit it.

A Kafka client's connection has two steps. First it connects to a bootstrap address to ask "who is the leader for this partition?" That connection can succeed. The broker then replies with an address for the client to use for the actual partition leader — and that's the advertised.listeners value. If that address is a hostname that only resolves inside the Docker network the broker lives in, an external client can complete step one and then fail every subsequent request, because it's being told to connect somewhere it fundamentally cannot reach.

Client                            Broker (bootstrap: localhost:9092)
  |----- 1. bootstrap connect -------->|
  |<---- "leader for orders-0 is       |
  |       advertised at kafka:9092" ---|
  |
  |----- 2. connect to kafka:9092 ---->  X   unresolvable outside
  |                                          the Docker network
  |
  '--> LEADER_NOT_AVAILABLE — repeats forever, every request

Step 1 succeeds because it uses the address you gave the client directly. Step 2 fails silently from the client's point of view — it just can't reach kafka:9092 — and every retry repeats the same doomed handoff, which is why the symptom looks like "connects fine, then nothing ever works."

# ❌ broker only advertises its internal Docker hostname
KAFKA_LISTENERS=PLAINTEXT://0.0.0.0:9092
KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092
# a client on the host machine can reach the bootstrap port,
# but "kafka" doesn't resolve outside the Docker network —
# every request after the first fails the same way, forever

# ✅ two listeners: one for other containers, one for the host
KAFKA_LISTENERS=INTERNAL://0.0.0.0:9092,EXTERNAL://0.0.0.0:9093
KAFKA_ADVERTISED_LISTENERS=INTERNAL://kafka:9092,EXTERNAL://localhost:9093
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP=INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT
KAFKA_INTER_BROKER_LISTENER_NAME=INTERNAL

# docker-compose.yml — expose the external port to the host:
#   ports:
#     - "9093:9093"

Other containers on the same Docker network connect via kafka:9092 (the internal listener); anything outside that network — your host machine, a local script, a different compose project — connects via localhost:9093 (the external listener). Each listener advertises an address that's actually reachable from where its clients run. This is the single most common Kafka Docker misconfiguration, and it produces exactly the confusing "connects, then fails on everything" pattern this error describes.

Kubernetes: a related but distinct cause

In Kubernetes the same failure mode shows up for a different reason. A Kafka StatefulSet behind a headless service needs each broker pod to advertise its own address, not one value shared across the whole set:

# pod kafka-0 advertises its own stable headless-service hostname:
KAFKA_ADVERTISED_LISTENERS=INTERNAL://kafka-0.kafka-headless.default.svc.cluster.local:9092

# pod kafka-1 advertises a different one, derived from its own ordinal:
KAFKA_ADVERTISED_LISTENERS=INTERNAL://kafka-1.kafka-headless.default.svc.cluster.local:9092

# ❌ every pod advertising the same hardcoded hostname (or the
# StatefulSet's service name instead of each pod's own identity)
# routes clients to a leader address only some pods can reach

If Kafka is also exposed outside the cluster — via a LoadBalancer, NodePort, or Ingress — the same rule applies one layer further out: that external listener has to advertise the address external clients actually connect through (the load balancer hostname, or the node's external IP and mapped port), not the pod's internal cluster-local address.

Fix 2: confirm it isn't a genuine leadership gap

Outside of Docker listener issues, this can also mean a partition genuinely has no eligible leader — every replica is on a broker that's down, or unclean leader election is disabled and no in-sync replica remains:

kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders

# a healthy partition shows a real leader id:
#   Partition: 0  Leader: 1  Replicas: 1,2,3  Isr: 1,2,3
#
# a partition close to losing its leader shows a shrunk ISR:
#   Partition: 0  Leader: none  Replicas: 1,2,3  Isr: 2
#                                                       ^ only one in-sync replica left,
#                                                         and if that broker is also down,
#                                                         no leader can be elected
#
# the worse case — no in-sync replicas left at all:
#   Partition: 0  Leader: none  Replicas: 1,2,3  Isr:
#                                                     ^ every replica has fallen out of sync;
#                                                       recovery means either restarting one
#                                                       back into the ISR, or accepting data
#                                                       loss via unclean leader election

If Leader genuinely shows none, this is a cluster health problem, not a client configuration problem: check which brokers in Replicas are actually up, and whether unclean.leader.election.enable is deliberately set to false (the safer default, since enabling it can elect a leader with an incomplete log and lose acknowledged data). Bringing enough replicas back online resolves it; forcing unclean election is a data-loss trade-off, not a first response.

How to tell which problem you have

Verifying the fix worked

Don't just redeploy and hope the retries stop — prove it from the client's actual network, not from inside the broker's own container:

# run this from wherever the CLIENT actually runs, not the broker host:
kafka-broker-api-versions.sh --bootstrap-server <external-address>:9093

# kcat (kafkacat) is often quicker to reach for:
kcat -b <external-address>:9093 -L

# if the brokers it lists are addressed by something you can't resolve
# or reach from here (e.g. "kafka:9092" from outside Docker),
# advertised.listeners is still wrong — the config change didn't take

Both commands fail fast and clearly when an advertised address isn't reachable, instead of leaving you to infer it from another round of confusing client retries.

Debugging checklist

• ✓ Did the topic get created moments before the warning (explicitly, or implicitly via auto.create.topics.enable)? It likely resolves on its own within seconds
• ✓ Run kafka-topics.sh --describe — is Leader a real broker ID, or literally none?
• ✓ If a real leader exists but the client still fails: check advertised.listeners against where the client actually runs
• ✓ Running in Docker? Confirm you have a separate internal and external listener, each advertising a reachable address
• ✓ Running in Kubernetes? Confirm each pod advertises its own headless-service hostname, and any external listener advertises the LoadBalancer/NodePort/Ingress address
• ✓ Does the error list one topic in braces, or several? Several points toward a cluster-wide cause rather than one misbehaving topic
• ✓ If Leader: none genuinely, check which replica brokers are down and whether they can be restarted
• ✓ Only consider unclean.leader.election.enable=true as a last resort — it can elect a leader with data loss
• ✓ After changing advertised.listeners, confirm it with kafka-broker-api-versions.sh or kcat -L from the client's own network before assuming it's fixed