Kafka REST生产Avro消息报错40801 Schema注册失败

问题表现 #

• 执行Avro类型消息生产操作时，携带自定义Schema向Kafka REST接口发起POST请求后返回错误，流程无法推进
• 接口返回错误码40801，响应内容如下：

{
    "error_code": 40801,
    "message": "Error when registering schema. format = AVRO, subject = teste-value, schema = {\"type\":\"record\",\"name\":\"teste\",\"fields\":[{\"name\":\"name\",\"type\":\"string\"}]}"
}

• 触发报错的请求命令如下：

curl -X POST -H "Content-Type: application/vnd.kafka.avro.v2+json" \
          -H "Accept: application/vnd.kafka.v2+json" \
          --data '{"value_schema": "{\"type\": \"record\", \"name\": \"teste\", \"fields\": [{\"name\": \"name\", \"type\": \"string\"}]}", "records": [{"value": {"name": "teste"}}]}' \
          "http://localhost:38082/topics/teste"

故障原因 #

注意：请求中定义的Avro Schema语法完全合规，不需要调整Schema字段结构，问题和Schema写法无关

该错误本质是Kafka REST Proxy无法完成Avro Schema的注册操作，所有触发场景都围绕Schema Registry连接异常：

• REST Proxy配置中填写的Schema Registry地址错误、端口不匹配，或Schema Registry服务本身未启动
• 网络访问限制导致REST Proxy所在节点无法连通Schema Registry服务端口
• Schema Registry开启了访问鉴权，但REST Proxy侧未配置对应鉴权凭据，注册请求被拒绝
• 容器化部署场景下，容器网络未打通、端口映射配置错误，REST Proxy无法访问到Schema Registry服务

修复步骤 #

1. 先验证Schema Registry服务可用性
   直接调用Schema Registry原生接口校验服务状态，默认服务端口为8081，执行命令：

   curl http://<Schema Registry部署地址>:8081/subjects
   

   正常情况下会返回空数组或已存在的Schema主题列表，若请求超时或连接拒绝，先启动Schema Registry服务再做后续排查。
2. 核对REST Proxy配置
   打开REST Proxy的配置文件kafka-rest.properties，确认schema.registry.url配置项的值为Schema Registry的可访问地址，IP、端口无拼写错误。
   若Schema Registry开启了鉴权，补充对应鉴权配置，以Basic认证为例需新增：

   schema.registry.basic.auth.credentials.source=USER_INFO
   schema.registry.basic.auth.user.info=<鉴权用户名>:<鉴权密码>
   

3. 容器化部署场景专项检查
   若用Docker/Docker Compose部署测试环境，确认REST Proxy和Schema Registry在同一个自定义容器网络内，schema.registry.url不要填localhost，需填写Schema Registry对应的容器服务名，端口使用容器内默认服务端口8081，不要使用映射到宿主机的外部端口。
4. 所有配置修改完成后重启Kafka REST Proxy服务，重新执行之前的消息发送请求即可正常写入Avro消息。

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