t8y2/dbx · error

no RocketMQ master broker found for topic %s

Error message

no RocketMQ master broker found for topic %s

What it means

queryMessagesByKey resolves the topic route via ExamineTopicRouteInfo and collects only broker addresses registered under brokerId '0' (the master). If the topic's route has no BrokerData entry with a non-empty master address, the library cannot query any broker and returns this error. It means the topic route exists but has no usable master broker endpoint.

Source

Thrown at agents/drivers/rocketmq/messages.go:240

	connectTimeout time.Duration,
	topic string,
	key string,
	maxNum int,
	beginTimestamp int64,
	endTimestamp int64,
) ([]*admin.MessageExt, error) {
	route, err := client.ExamineTopicRouteInfo(ctx, topic)
	if err != nil {
		return nil, err
	}
	targets := make([]messageQueueTarget, 0, len(route.BrokerDatas))
	for _, broker := range route.BrokerDatas {
		if address := broker.BrokerAddrs["0"]; address != "" {
			targets = append(targets, messageQueueTarget{BrokerName: broker.BrokerName, Address: address})
		}
	}
	if len(targets) == 0 {
		return nil, fmt.Errorf("no RocketMQ master broker found for topic %s", topic)
	}
	messages := make([]*admin.MessageExt, 0)
	successCount := 0
	var lastErr error
	for _, target := range targets {
		response, requestErr := invokeRemotingAllowCodes(ctx, target.Address, connectTimeout,
			buildQueryMessageCommand(topic, key, maxNum, beginTimestamp, endTimestamp),
			remoting.Success, queryMessageNotFoundCode)
		if requestErr != nil {
			lastErr = requestErr
			continue
		}
		successCount++
		if response.Code == queryMessageNotFoundCode || len(response.Body) == 0 {
			continue
		}
		for _, message := range primitive.DecodeMessage(response.Body) {
			queueID := 0

View on GitHub (pinned to c0390bff16)

Solutions

1. Verify with mqadmin clusterList/brokerStatus that a master broker (brokerId=0) for the topic's group is running and registered.
2. Set brokerId=0 in the master's broker.conf (slaves use 1+).
3. Check brokerIP1/brokerListenPort resolve to an address reachable by the client.
4. If the route is stale, recreate the topic: mqadmin deleteTopic then mqadmin updateTopic.
5. Restart the master broker so it re-registers with the NameServer.

Example fix

// before
brokerId = 1
// after (on the intended master)
brokerId = 0

// Resolve route and check for a master (brokerId "0") before querying.
route, err := client.ExamineTopicRouteInfo(ctx, topic)
if err != nil { return err }
hasMaster := false
for _, bd := range route.BrokerDatas {
    if addr, ok := bd.BrokerAddrs["0"]; ok && addr != "" { hasMaster = true; break }
}
if !hasMaster {
    return fmt.Errorf("topic %s has no master broker; run: mqadmin clusterList", topic)
}

func hasMasterBroker(route *admin.TopicRoute) bool {
    for _, bd := range route.BrokerDatas {
        if addr, ok := bd.BrokerAddrs["0"]; ok && addr != "" {
            return true
        }
    }
    return false
}

When it happens

Trigger: Calling viewMessage or queryMessageByKey (message-by-key lookup or message-trace query) when the topic's route from the NameServer lists BrokerDatas whose BrokerAddrs map lacks the '0' key, has an empty '0' value, or only contains slave broker IDs.

Common situations: Master broker down and deregistered while the NameServer still returns the topic route; broker running with brokerId != 0; stale route left after a broker was removed; NameServer holding cached route info after a broker crash.

Related errors

• query messages for topic %s on all masters: %w
• no writable queue for topic %s
• invalid queue offset: %w
• no RocketMQ master broker found for topic %s
• query topic stats for %s on all masters: %w

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/b78cb4a37fd168dd. Report an issue: GitHub.