Apache Kafka 是强大的消息平台，但也容易因为网络、Broker 状态、分区 Leader、消费者 Offset、Topic 配置或认证配置产生错误。排查 Kafka 问题时，关键不是只记住错误名，而是把错误归类到连接、元数据、消费位置、请求超时、复制和安全认证几个方向。
核心要点
- Broker 不可用通常先查进程状态和网络连通性。
- Leader 不可用、Not Leader For Partition 与分区 Leader 选举和元数据刷新有关。
- Offset 超出范围通常与消费者落后、消息保留策略和 offset 重置有关。
- 请求超时可能来自网络延迟、Broker 负载过高或消息过大。
- 认证失败要同时核对客户端凭据、Broker 配置、SASL/SSL 机制和证书信任链。
Kafka 常见错误速查
| 错误 | 常见原因 | 优先检查 |
|---|---|---|
| Broker 不可用 | Broker 未运行或网络不可达 | 进程、端口、防火墙、网络变更 |
| Leader 不可用 | 分区 Leader 所在 Broker 故障或未完成选举 | Broker 状态、分区 Leader、集群日志 |
| Offset 超出范围 | 消费者读取的 offset 已被删除 | 保留策略、消费者 offset、重置策略 |
| 请求超时 | 网络慢、Broker 过载、消息过大 | 延迟、Broker 负载、超时参数 |
| Unknown Topic or Partition | Topic 或分区不存在 | Topic 名称、自动创建配置、元数据 |
| Not Leader For Partition | 客户端访问了非 Leader Broker | 元数据刷新、Leader 选举日志 |
| 发送失败 | 网络、Broker、生产者配置问题 | bootstrap.servers、acks、retries |
| Replication Factor 过高 | 副本数大于 Broker 数 | Broker 数量、Topic 创建参数 |
| 认证失败 | SASL/SSL 配置或凭据不匹配 | 用户名密码、证书、认证机制 |
1. Broker 不可用
“Broker 不可用”是 Kafka 中常见错误之一。当生产者或消费者尝试连接到未运行或无法访问的 Broker 时，通常会出现该错误。
可能原因
- Broker 进程未启动或异常退出。
- 客户端访问的地址或端口错误。
- 防火墙、路由或网络策略阻断连接。
- Broker 正在重启，客户端元数据暂未刷新。
处理方法
首先登录到应运行 Broker 的服务器，检查进程是否存在：
ps -ef | grep kafka
如果 Broker 已关闭，先重启 Broker。如果 Broker 正在运行，则继续检查监听端口、防火墙设置和最近的网络变更。
2. Leader 不可用
当某个分区的 Leader 不可用时，会出现 Leader 不可用错误。常见原因是原 Leader 所在 Broker 宕机，而 Kafka 尚未完成新的 Leader 选举。
处理方法
先确保宕机 Broker 已重启并重新加入集群。Kafka 通常会自动将 Leader 重新分配给其他 Broker。
如果没有自动恢复，需要检查 Broker 日志、控制器日志和分区状态。原文提到，也可以使用带有 --alter-partitions 选项的 kafka-topics.sh 命令强制进行 Leader 选举或手动重新分配分区。实际操作前应先确认当前 Kafka 版本支持的命令参数。
3. Offset 超出范围
Offset 超出范围在消费者中很常见。当消费者尝试从一个不存在的 offset 读取数据时，就会出现这种错误。常见原因是消费者长时间宕机，目标消息已经根据保留策略被清理。
处理方法
可以将消费者 offset 重置到最早或最新位置。原文示例：
kafka-consumer-groups.sh –bootstrap-server localhost:9092 –group my-group –reset-offsets –to-earliest –execute –topic my-topic
该命令会将 offset 重置为主题中最早可用消息。如果不希望再次发生，需要检查消息保留策略，并评估消费者落后时的恢复能力。
4. 请求超时
当向 Kafka Broker 发送的请求超过配置的超时时间，就会发生请求超时。原因可能是网络问题、Broker 过载，或消息体积过大导致处理时间过长。
处理方法
优先检查：
- 网络延迟是否升高。
- Broker CPU、磁盘、网络和请求队列是否压力过大。
- 生产者或消费者超时参数是否过短。
- 单条消息是否过大。
可以考虑增加生产者或消费者端的超时设置，例如 request.timeout.ms 或 session.timeout.ms。如果问题来自消息过大，可以考虑增大 Broker 的 message.max.bytes，或优化消息大小和批处理方式。
5. Unknown Topic or Partition
该错误通常发生在生产者或消费者访问不存在的 Topic 或分区时。常见原因包括 Topic 名称拼写错误、Topic 尚未创建、分区编号不存在，或自动创建 Topic 功能被关闭。
处理方法
先仔细检查生产者或消费者配置中的 Topic 和分区名称。如果 Topic 不存在，可以创建 Topic：
kafka-topics.sh –create –topic my-new-topic –bootstrap-server localhost:9092 –partitions 3 –replication-factor 2
如果预期 Topic 应由自动创建功能创建，需要检查 Broker 配置，确认该功能是否被禁用。
6. Not Leader For Partition
该错误表示客户端尝试通信的 Broker 已不再是目标分区 Leader。它可能发生在 Kafka 正常运行期间的 Leader 重选过程中。
处理方法
该错误通常是暂时性的。Kafka 完成 Leader 重分配后，客户端刷新元数据即可恢复。
如果持续出现，可能说明 Leader 选举、Broker 稳定性或客户端元数据刷新存在问题。需要检查 Broker 日志中与 Leader 选举相关的错误或警告。原文还提到，可以考虑调整 leader.imbalance.check.interval.seconds，让 Kafka 更频繁地平衡 Leader。
7. 发送失败
发送失败可能由多种问题引起，例如网络问题、Broker 故障或生产者配置错误。
处理方法
排查顺序建议如下：
- 检查网络连接，确认生产者能访问 Kafka Broker。
- 确认 Broker 已启动并正常响应。
- 检查生产者关键配置，例如
bootstrap.servers、acks、retries。 - 如果原因仍不明确，将日志级别提高到
DEBUG，查看失败发生在元数据拉取、连接、序列化还是发送确认阶段。
8. Replication Factor 过高
当尝试创建复制因子高于可用 Broker 数量的 Topic 时，会遇到该错误。
处理方法
有两种选择：
- 降低 Topic 的复制因子。
- 增加 Broker 数量，使集群可以承载所需副本数。
如果复制因子来自数据冗余要求，不能简单降低，需要先扩容 Broker，再创建或调整 Topic。
9. 认证失败
认证错误通常发生在 Kafka 安全设置配置错误时。例如使用 SASL 或 SSL 进行客户端认证时，客户端凭据与 Broker 期望不匹配。
处理方法
检查项包括：
- 客户端用户名和密码是否正确。
- SSL 证书是否正确签名。
- truststore 是否配置了正确 CA 证书。
- Broker 和客户端是否使用相同 SASL 机制，例如
PLAIN或SCRAM-SHA-256。 - 客户端和 Broker 的安全协议配置是否一致。
Kafka 排障的通用顺序
- 先判断错误属于连接、元数据、消费位置、请求超时、复制还是认证。
- 再定位涉及的对象：Broker、Topic、Partition、Consumer Group、Producer 或安全配置。
- 查看客户端日志和 Broker 日志，确认错误发生阶段。
- 检查最近变更，例如扩容、重启、网络策略、认证配置或 Topic 创建参数。
- 修复后观察消费者 lag、生产者错误率、Broker 请求延迟和分区 Leader 状态。
FAQ
Offset 超出范围一定会丢数据吗？
如果目标 offset 对应的消息已经被保留策略清理，消费者无法再读取那部分消息。重置 offset 能恢复消费，但不能恢复已清理的数据。
Leader 不可用和 Not Leader For Partition 有什么区别？
Leader 不可用强调目标分区暂时没有可服务的 Leader；Not Leader For Partition 表示客户端访问的 Broker 不是当前 Leader。两者都与 Leader 状态和元数据有关，但排查角度不同。
请求超时时，应该先调大超时时间吗？
不应只调参数。先判断是否存在网络延迟、Broker 过载、磁盘压力或消息过大。参数调整只能缓解部分场景，不能替代根因排查。
结语
Kafka 是复杂系统，错误通常来自连接、分区 Leader、offset、请求超时、复制因子或安全认证。稳定运行 Kafka 的关键，是在错误出现时快速判断类别，并沿着 Broker、Topic、Partition、Consumer Group 和客户端配置逐层排查。主动监控、正确配置和理解 Kafka 内部机制，能在问题升级前发现风险。
原文链接：https://www.meshiq.com/common-kafka-errors-and-how-to-resolve-them/
