t8y2/dbx · error

wait for RocketMQ broker registration after %v: %w

Error message

wait for RocketMQ broker registration after %v: %w

What it means

waitForBrokerRegistration polls the cluster until a master broker appears; when the context is cancelled/timed out after at least one prior failure, it wraps the last poll error with the context error using this message. It indicates the broker never registered within the timeout.

Source

Thrown at agents/drivers/rocketmq/connection.go:197

	if pollInterval <= 0 {
		pollInterval = brokerRegistrationPollInterval
	}
	var lastErr error
	for {
		clusterInfo, err := examine(ctx)
		if err == nil && hasMasterBroker(clusterInfo) {
			return clusterInfo, nil
		}
		if err != nil {
			lastErr = err
		}

		timer := time.NewTimer(pollInterval)
		select {
		case <-ctx.Done():
			timer.Stop()
			if lastErr != nil {
				return nil, fmt.Errorf("wait for RocketMQ broker registration after %v: %w", lastErr, ctx.Err())
			}
			return nil, fmt.Errorf("wait for RocketMQ broker registration: %w", ctx.Err())
		case <-timer.C:
		}
	}
}

func hasMasterBroker(info *admin.ClusterInfo) bool {
	if info == nil {
		return false
	}
	for _, broker := range info.BrokerAddrTable {
		if broker != nil && broker.BrokerAddrs["0"] != "" {
			return true
		}
	}
	return false
}

View on GitHub (pinned to c0390bff16)

Solutions

1. Increase the timeout budget passed to buildClient/waitForBrokerRegistration and retry
2. Inspect the wrapped lastErr for the real root cause (connection refused, auth, etc.)
3. Verify brokers are running and registered with the name servers (mqadmin clusterList)

Example fix

// before
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
// after
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)

// pre-check: confirm brokers are registered before long waits
info, err := adminClient.FetchClusterInfo()
if err != nil || len(info.BrokerAddrTable) == 0 {
    return errors.New("no brokers registered; fix cluster before connecting")
}

client, err := buildClient(ctx, cfg)
if err != nil && strings.Contains(err.Error(), "broker registration") {
    time.Sleep(10 * time.Second)
    client, err = buildClient(longerCtx, cfg)
}

When it happens

Trigger: buildClient calls waitForBrokerRegistration with a context deadline shorter than broker startup; lastErr from a prior poll is non-nil when ctx.Done fires.

Common situations: Slow disk/JVM startup exceeding the wait window; network partition to broker ports; wrong namesrv_addr pointing at a cluster with no brokers; tight timeouts in CI.

Related errors

• IoTDB is not reachable at {host}:{port}
• ZooKeeper connection timed out before a session was establis
• ETCD_HISTORY_TIMEOUT
• ZooKeeper connection timed out before a session was establis
• ZooKeeper session expired during connection

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