kafka-python无法读取Kafka消息头，Kafka UI与Golang客户端可正常读取

问题描述 #

kafka-python无法读取Kafka消息头，但Golang的Kafka客户端可以正常读取，所有消息的头信息均无法被识别。

代码示例 #

for message in consumer:
    # message value and key are raw bytes -- decode if necessary!
    # e.g., for unicode: `message.value.decode('utf-8')`
    print(
        "%s:%d:%d: key=%s headers=%s"
        % (
            message.topic,
            message.partition,
            message.offset,
            message.key,
            "".join(message.headers),
        )
    )

预期结果 #

• Kafka UI可显示消息的Kafka头信息（对应截图）
• Golang的Kafka客户端可读取消息头（对应截图）

实际结果 #

kafka-python无法读取任何消息头（对应截图），原始ConsumerRecord信息如下：

ConsumerRecord(topic='mz-core-document-manager-responses', partition=2, leader_epoch=-1, offset=***, timestamp=1757941918771, timestamp_type=0, key=b'***', value=b'***', headers=[], checksum=***, serialized_key_size=93, serialized_value_size=1127, serialized_header_size=-1)

版本信息 #

• Python：3.13/3.10
• kafka-python：基于git commit 512d0a0b8d71cf7f34f1b23f8a42d52c28af3266（兼容v2.0.2内容）

解决方法 #

1. 显式指定Kafka协议版本
   消息头是Kafka 0.11.0.0版本引入的特性，若kafka-python客户端未指定正确的协议版本，会自动降级导致无法读取头信息。初始化消费者时添加api_version参数，匹配你的Kafka集群版本：

   from kafka import KafkaConsumer
   
   consumer = KafkaConsumer(
       'mz-core-document-manager-responses',
       bootstrap_servers=['你的Kafka broker地址:9092'],
       api_version=(0, 11, 0),  # 替换为集群实际版本
       # 其他必要配置（如group_id等）
   )
   

2. 验证消息头格式
   确认生产者写入的消息头是标准的(key, value)字节对格式。kafka-python中message.headers会返回此类元组的列表，若生产者有自定义处理，需保证格式符合Kafka协议规范。

3. 升级kafka-python版本
   你当前使用的commit版本可能存在头信息读取的已知问题，尝试切换到官方稳定版v2.0.2或更新版本，排查是否为版本bug导致。

内容的提问来源于stack exchange，提问作者Irina