t8y2/dbx · critical

no RocketMQ master broker found

Error message

no RocketMQ master broker found

What it means

masterBrokerAddresses collects the master (brokerId=0) address for a broker group from the nameserver route; this error is thrown when no master broker address can be resolved at all (no route data, no brokerId "0" entry, and no fallback address configured).

Solutions

1. Verify the agent's nameserver address(es) are correct and reachable (namesrvAddr / env config) and that brokers are registered: check with `mqadmin clusterList`
2. Ensure a master broker (brokerId=0) for the target group is running and registered; start/restart the master if it crashed
3. Correct the brokerName parameter if one was passed — a wrong name yields no route and empty fallback
4. Configure the fallback address in agent config so operations work even when route discovery returns nothing

Example fix

// before
agent := rocketmq.NewAgent(rocketmq.Config{}) // nameserver unset
// after
agent := rocketmq.NewAgent(rocketmq.Config{
    NameServerAddrs: []string{"10.0.0.1:9876", "10.0.0.2:9876"},
})

route, err := adminClient.ExamineTopicRouteInfo(ctx, topic)
if err != nil { return err }
if len(route.BrokerDatas) == 0 || route.BrokerDatas[0].BrokerAddrs["0"] == "" {
    return fmt.Errorf("no master broker registered; check nameserver and broker health")
}

When it happens

Trigger: Any operation needing a broker address — createTopic, deleteTopic, updatePartitions, getTopicConfig, alterTopicConfig, deleteConsumerGroup, alterSubscriptionGroupConfig, collectSubscriptionGroupConfigs — is called while the agent has no reachable nameserver route or the broker group registers only slaves (no id 0).

Common situations: Nameserver down or wrong namesrvAddr in agent config; broker cluster registered with only slave brokers (master crashed); network/partition between agent and nameserver; brokerName typo so the route lookup finds nothing and the fallback is empty.

Related errors

• invalid queue offset
• no RocketMQ master broker found for topic
• query messages for topic
• query topic stats for
• read topic config : ; fallback snapshot

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

Appendix: source

Thrown at agents/drivers/rocketmq/topics.go:444

	addresses := make([]string, 0)
	for _, name := range sortedKeys(info.BrokerAddrTable) {
		if brokerName != "" && brokerName != name {
			continue
		}
		if address := info.BrokerAddrTable[name].BrokerAddrs["0"]; address != "" {
			addresses = append(addresses, address)
		}
	}
	if len(addresses) == 0 {
		a.mu.RLock()
		fallback := a.brokerAddr
		a.mu.RUnlock()
		if fallback != "" {
			addresses = append(addresses, fallback)
		}
	}
	if len(addresses) == 0 {
		return nil, fmt.Errorf("no RocketMQ master broker found")
	}
	return addresses, nil
}

func (a *rocketMQAgent) brokerAddressForName(brokerName string) (string, error) {
	addresses, err := a.masterBrokerAddresses(brokerName)
	if err != nil {
		return "", err
	}
	return addresses[0], nil
}

type parsedMessageQueue struct {
	Topic      string
	BrokerName string
	QueueID    int
}

View on GitHub (pinned to c0390bff16)