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).

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)

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

• no RocketMQ master broker found for topic %s
• query messages for topic %s on all masters: %w
• invalid queue offset: %w
• query topic stats for %s on all masters: %w
• read topic config %s: %v; fallback snapshot: %w

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