Kafka consumer config

session.timeout.ms: how long a dead consumer keeps its partitions

Consumer config · default 45000 (45 seconds) · Apache Kafka 4.3

session.timeout.ms is how long the group coordinator waits for a heartbeat from a consumer before it removes the member and gives its partitions to the rest of the group (default 45000, 45 seconds). A crashed consumer keeps its partitions, unread, for that long. It applies to the classic group protocol; with group.protocol=consumer the broker setting group.consumer.session.timeout.ms applies instead.

Config: session.timeout.ms (consumer)
Default: 45000 (45 seconds)
Valid values: Within the broker group.min.session.timeout.ms (6000) and group.max.session.timeout.ms (1800000)
Also set at: With group.protocol=consumer (KIP-848), the session timeout is the broker setting group.consumer.session.timeout.ms (default 45000), and the client value is not used.
Reference: Apache Kafka documentation for session.timeout.ms

Scenario 02.3.1 · Consumer crash & session timeout step 3

c1 crashed · p0 stalls, c2 keeps consuming. c1 crashed at t=1000 but still owns p0 until session.timeout.ms (2000 ms here; timings are compressed, real brokers require at least 6 s) elapses. New records on p0 are NOT consumed - its lag grows - while c2 keeps draining p1. This partial stall is what makes a crash different from a clean leave. Open this step in the full playground

What it does

A consumer in a group sends heartbeats from a background thread every heartbeat.interval.ms (3 seconds by default). If the coordinator hears nothing for session.timeout.ms, it declares the member dead and rebalances its partitions onto the others. A clean shutdown sends a leave request, so only crashes, freezes and network partitions wait out the timeout. Heartbeats come from their own thread, so slow processing does not trip it; that is max.poll.interval.ms.

The trade-off

A short timeout moves a dead consumer partitions quickly, but long garbage collection pauses or brief network trouble then cause needless rebalances. A long timeout rides those out, but after a real crash the partitions sit unread for the whole timeout while lag grows. Static membership (group.instance.id) lets a restarted consumer take back its partitions without a rebalance, as long as it returns within the timeout.

Advice

Keep heartbeat.interval.ms at no more than a third of session.timeout.ms.
The 45 s default suits most groups; lower it only if partitions stalled for 45 s after a crash hurt more than occasional extra rebalances.
For rolling restarts without rebalances, use static membership with a session timeout longer than a restart.

See it in the simulator

Kafka consumer crash and session.timeout.ms (Consumer crash & session timeout) Step 3: c1 crashed · p0 stalls, c2 keeps consuming Open at this step: Kafka consumer crash and session.timeout.ms
Kafka static membership: group.instance.id avoids rebalances (Static membership: avoid rebalance) Step 5: static member rejoins in time Open at this step: Kafka static membership: group.instance.id avoids rebalances

Related configs

All Kafka configs