---
name: kafka-consumer-group-stuck-restart
description: Restart a consumer group that has stopped advancing its offsets, after confirming the lag is real and not a monitoring artefact.
runbook:
  schema_version: v1
  semver: 1.0.0
  profile: P1
  min_runtime_profile: R1
  domain: data-pipelines
  targets:
    - kafka
  trigger: alert
  execution: human-with-agent
  risk: reversible-write
  blast_radius: service
  duration: 5-30m
  capabilities:
    - cli:kafka-consumer-groups
  publisher: std
  lang: en
  license: CC-BY-4.0
  inputs:
    group:
      type: string
      required: true
      description: consumer group id
  steps:
    - id: s1
      kind: check
      title: Capture current lag
      tool: cli:kafka-consumer-groups
      command: kafka-consumer-groups --describe --group {{inputs.group}}
      expect: a LAG column is present
      assert:
        exit_code: 0
        stdout_matches: LAG
      on_fail: escalate:s9
      next: s2
    - id: s2
      kind: decision
      title: Determine lag spread
      question: Is lag growing on all partitions or on one?
      branches:
        all: s3
        single: s4
        default: s9
    - id: s3
      kind: action
      title: Restart the consumer group
      risk: reversible-write
      tool: cli:kafka-consumer-groups
      next: s5
    - id: s4
      kind: check
      title: Inspect the lagging partition
      tool: cli:kafka-consumer-groups
      expect: one partition holds the lag
      on_fail: escalate:s9
      next: s5
    - id: s5
      kind: wait
      title: Wait for offsets to advance
      until: LAG decreases on every partition
      timeout: 5m
      retry:
        max: 3
        target: s5
      next: end:success
    - id: s9
      kind: escalate
      title: Escalate to the platform team
      to: team:platform
  source:
    url: https://runbooks.directory/r/std/kafka-consumer-group-stuck-restart/source.md
    fetched_at: 2026-09-02
    upstream_state: current
---

## When to reach for this

A consumer group alert has fired and offsets are not advancing. Confirm the lag is real
before restarting anything: a monitoring gap looks identical to a stalled group from the
alert alone.

## Notes

Restarting a consumer group is reversible, but it re-triggers rebalancing across every
consumer in the group. On a large group that is disruptive enough to be worth confirming
the lag first, which is why step one is a check and not the restart.