{
  "id": "kafka/consumer-group-stale-metadata",
  "signature": "org.apache.kafka.common.errors.StaleMemberEpochException: The member epoch 5 has been fenced by the group coordinator",
  "signature_zh": "org.apache.kafka.common.errors.StaleMemberEpochException：成员纪元5已被组协调器隔离",
  "regex": "StaleMemberEpochException.*member epoch.*has been fenced",
  "domain": "kafka",
  "category": "runtime_error",
  "subcategory": null,
  "root_cause": "Consumer member's epoch (generation) is outdated because the group coordinator has rebalanced or the consumer's session timed out, leading to a fenced member.",
  "root_cause_type": "generic",
  "root_cause_zh": "消费者成员的纪元（代）已过期，因为组协调器已重新平衡或消费者的会话超时，导致成员被隔离。",
  "versions": [],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "",
      "why_fails": "This can make the consumer unresponsive for longer periods, worsening rebalance issues and causing the group to stall; it does not prevent epoch fencing due to rebalances.",
      "fail_rate": 0.5,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "Static membership only prevents unnecessary rebalances during brief disconnections; if the consumer actually fails or is fenced, the epoch will still be stale.",
      "fail_rate": 0.4,
      "condition": "",
      "sources": []
    },
    {
      "action": "",
      "why_fails": "This causes a full rebalance and may temporarily resolve the error, but the underlying cause (e.g., network issues, slow processing) remains, so the error will recur.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Implement a consumer rebalance listener to detect rebalances and reset state. For Java consumers: `consumer.subscribe(Collections.singletonList(topic), new ConsumerRebalanceListener() { ... })`",
      "success_rate": 0.85,
      "how": "Implement a consumer rebalance listener to detect rebalances and reset state. For Java consumers: `consumer.subscribe(Collections.singletonList(topic), new ConsumerRebalanceListener() { ... })`",
      "condition": "",
      "sources": []
    },
    {
      "action": "Increase 'heartbeat.interval.ms' to a value lower than 'session.timeout.ms' (e.g., set heartbeat to 1000 ms and session timeout to 10000 ms) to ensure timely heartbeats and reduce session expiry.",
      "success_rate": 0.8,
      "how": "Increase 'heartbeat.interval.ms' to a value lower than 'session.timeout.ms' (e.g., set heartbeat to 1000 ms and session timeout to 10000 ms) to ensure timely heartbeats and reduce session expiry.",
      "condition": "",
      "sources": []
    },
    {
      "action": "If using static group membership, ensure 'group.instance.id' is unique per consumer and stable across restarts. Example: `props.put(ConsumerConfig.GROUP_INSTANCE_ID_CONFIG, \"consumer-1\");`",
      "success_rate": 0.75,
      "how": "If using static group membership, ensure 'group.instance.id' is unique per consumer and stable across restarts. Example: `props.put(ConsumerConfig.GROUP_INSTANCE_ID_CONFIG, \"consumer-1\");`",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Implement a consumer rebalance listener to detect rebalances and reset state. For Java consumers: `consumer.subscribe(Collections.singletonList(topic), new ConsumerRebalanceListener() { ... })`",
    "Increase 'heartbeat.interval.ms' to a value lower than 'session.timeout.ms' (e.g., set heartbeat to 1000 ms and session timeout to 10000 ms) to ensure timely heartbeats and reduce session expiry.",
    "If using static group membership, ensure 'group.instance.id' is unique per consumer and stable across restarts. Example: `props.put(ConsumerConfig.GROUP_INSTANCE_ID_CONFIG, \"consumer-1\");`"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://kafka.apache.org/documentation/#consumer_group_rebalancing",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.83,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2024-05-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}