文档中心

消息队列 RocketMQ版

常见问题

消息发送常见问题

本文介绍消息队列 RocketMQ版在消息发送过程中的常见问题及解决方案。

SpringBoot 发送 RocketMQ 5.x 顺序消息时报错 TopicMessageType validate failed 如何处理？

问题描述

在 SpringBoot 项目中使用 rocketmq-spring-boot-starter 调用 rocketMQTemplate.syncSendOrderly() 发送顺序消息时，客户端明确请求发送顺序（FIFO）消息，服务端却校验消息类型为普通（NORMAL）消息，导致发送失败，并出现如下报错：

问题原因

服务端校验机制：RocketMQ 5.x 引入了严格的消息类型校验机制。对于标记为 FIFO（顺序）的 Topic，Broker 会校验每条消息的属性中是否包含 __SHARDINGKEY，只有携带该属性的消息才会被识别为 FIFO 类型，否则将被判定为 NORMAL 普通消息并拒绝写入。

客户端协议缺陷：rocketmq-spring-boot-starter 默认使用 Remoting 协议，其底层依赖的 rocketmq-client 在发送顺序消息时，不会自动添加 __SHARDINGKEY 属性。

类型匹配失败：即使客户端调用了顺序发送接口，消息因缺少关键标识导致类型匹配失败，Broker 会将其判定为 NORMAL 类型，因为与 FIFO Topic 的类型不一致而拒绝写入，返回 TopicMessageType validate failed 错误。

解决方案

方案一：使用 5.x gRPC 协议

gRPC 是 RocketMQ 5.x 标准协议，发送时设置 MessageGroup，由 Proxy 内部将其转换为 __SHARDINGKEY 属性，满足 FIFO 消息校验。

方案二：手动添加 __SHARDINGKEY 属性

在保持 Remoting 协议的前提下，发送消息时手动添加 __SHARDINGKEY 属性，使 Broker 能够正确识别顺序消息。

方案三：创建普通消息类型的 Topic

使用普通类型的 Topic 发送顺序消息，服务端不会进行严格的消息类型校验，可避免类型不匹配报错。

方案四：切换至 RocketMQ 4.x 实例与 SDK

切换至 RocketMQ 4.x 版本的实例，并使用对应的 4.x SDK 收发顺序消息。

最近更新时间：2026.04.09 15:29:37

这个页面对您有帮助吗？

有用

无用