{
  "id": "kafka/transactional-coordinator-fenced",
  "signature": "org.apache.kafka.common.errors.TransactionalCoordinatorFencedException: The transactional coordinator with epoch 5 has been fenced by a newer epoch 6",
  "signature_zh": "org.apache.kafka.common.errors.TransactionalCoordinatorFencedException: 纪元 5 的事务协调器已被较新的纪元 6 隔离",
  "regex": "org\\.apache\\.kafka\\.common\\.errors\\.TransactionalCoordinatorFencedException: The transactional coordinator with epoch .* has been fenced by a newer epoch .*",
  "domain": "kafka",
  "category": "protocol_error",
  "subcategory": null,
  "root_cause": "A transactional coordinator was replaced by a new coordinator with a higher epoch (e.g., after a leader change), causing the old coordinator's requests to be rejected as fenced.",
  "root_cause_type": "generic",
  "root_cause_zh": "事务协调器被具有更高纪元的新的协调器替换（例如，在领导变更后），导致旧协调器的请求被拒绝为隔离状态。",
  "versions": [
    {
      "version": "Kafka 2.8.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.0.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.4.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kafka 3.6.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Increase the transaction.timeout.ms to a very high value",
      "why_fails": "Transaction timeout controls how long a transaction can remain open, not coordinator fencing; it does not prevent epoch conflicts.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Disable idempotent producer and transactions",
      "why_fails": "This avoids the error but disables exactly-once semantics, which may be required for the application; it is a workaround that changes behavior.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Handle the exception in the producer by retrying the transaction with a new transactional ID or by resetting the producer:\n\nproducer.initTransactions();\ntry {\n    producer.beginTransaction();\n    // Send messages\n    producer.commitTransaction();\n} catch (TransactionalCoordinatorFencedException e) {\n    // Close and recreate the producer to get a fresh coordinator\n    producer.close();\n    producer = createNewProducer();\n    producer.initTransactions();\n    // Retry the transaction\n}",
      "success_rate": 0.85,
      "how": "Handle the exception in the producer by retrying the transaction with a new transactional ID or by resetting the producer:\n\nproducer.initTransactions();\ntry {\n    producer.beginTransaction();\n    // Send messages\n    producer.commitTransaction();\n} catch (TransactionalCoordinatorFencedException e) {\n    // Close and recreate the producer to get a fresh coordinator\n    producer.close();\n    producer = createNewProducer();\n    producer.initTransactions();\n    // Retry the transaction\n}",
      "condition": "",
      "sources": []
    },
    {
      "action": "Ensure the transactional.id is unique per producer instance and that the broker's transaction.state.log.replication.factor is sufficient to avoid coordinator failures:\n\ntransaction.state.log.replication.factor=3\n\nAlso monitor the broker logs for coordinator changes and consider increasing the number of transaction coordinator threads.",
      "success_rate": 0.8,
      "how": "Ensure the transactional.id is unique per producer instance and that the broker's transaction.state.log.replication.factor is sufficient to avoid coordinator failures:\n\ntransaction.state.log.replication.factor=3\n\nAlso monitor the broker logs for coordinator changes and consider increasing the number of transaction coordinator threads.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "Handle the exception in the producer by retrying the transaction with a new transactional ID or by resetting the producer:\n\nproducer.initTransactions();\ntry {\n    producer.beginTransaction();\n    // Send messages\n    producer.commitTransaction();\n} catch (TransactionalCoordinatorFencedException e) {\n    // Close and recreate the producer to get a fresh coordinator\n    producer.close();\n    producer = createNewProducer();\n    producer.initTransactions();\n    // Retry the transaction\n}",
    "Ensure the transactional.id is unique per producer instance and that the broker's transaction.state.log.replication.factor is sufficient to avoid coordinator failures:\n\ntransaction.state.log.replication.factor=3\n\nAlso monitor the broker logs for coordinator changes and consider increasing the number of transaction coordinator threads."
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://kafka.apache.org/documentation/#transactional_id",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.84,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2023-06-05",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}