{"record":{"id":"a14b35c807b2b2d2","repo":"t8y2/dbx","slug":"wait-for-rocketmq-broker-registration-after-v-w","errorCode":null,"errorMessage":"wait for RocketMQ broker registration after %v: %w","messagePattern":"wait for RocketMQ broker registration after (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/rocketmq/connection.go","lineNumber":197,"sourceCode":"\tif pollInterval <= 0 {\n\t\tpollInterval = brokerRegistrationPollInterval\n\t}\n\tvar lastErr error\n\tfor {\n\t\tclusterInfo, err := examine(ctx)\n\t\tif err == nil && hasMasterBroker(clusterInfo) {\n\t\t\treturn clusterInfo, nil\n\t\t}\n\t\tif err != nil {\n\t\t\tlastErr = err\n\t\t}\n\n\t\ttimer := time.NewTimer(pollInterval)\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\ttimer.Stop()\n\t\t\tif lastErr != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"wait for RocketMQ broker registration after %v: %w\", lastErr, ctx.Err())\n\t\t\t}\n\t\t\treturn nil, fmt.Errorf(\"wait for RocketMQ broker registration: %w\", ctx.Err())\n\t\tcase <-timer.C:\n\t\t}\n\t}\n}\n\nfunc hasMasterBroker(info *admin.ClusterInfo) bool {\n\tif info == nil {\n\t\treturn false\n\t}\n\tfor _, broker := range info.BrokerAddrTable {\n\t\tif broker != nil && broker.BrokerAddrs[\"0\"] != \"\" {\n\t\t\treturn true\n\t\t}\n\t}\n\treturn false\n}","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/rocketmq/connection.go#L179-L215","documentation":"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.","triggerScenarios":"buildClient calls waitForBrokerRegistration with a context deadline shorter than broker startup; lastErr from a prior poll is non-nil when ctx.Done fires.","commonSituations":"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.","solutions":["Increase the timeout budget passed to buildClient/waitForBrokerRegistration and retry","Inspect the wrapped lastErr for the real root cause (connection refused, auth, etc.)","Verify brokers are running and registered with the name servers (mqadmin clusterList)"],"exampleFix":"// before\nctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n// after\nctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)","handlingStrategy":"retry","validationCode":"// pre-check: confirm brokers are registered before long waits\ninfo, err := adminClient.FetchClusterInfo()\nif err != nil || len(info.BrokerAddrTable) == 0 {\n    return errors.New(\"no brokers registered; fix cluster before connecting\")\n}","typeGuard":null,"tryCatchPattern":"client, err := buildClient(ctx, cfg)\nif err != nil && strings.Contains(err.Error(), \"broker registration\") {\n    time.Sleep(10 * time.Second)\n    client, err = buildClient(longerCtx, cfg)\n}","preventionTips":["Size timeouts to exceed broker JVM startup time","Log the wrapped lastErr to find the true root cause","Health-check the broker out-of-band before connecting"],"tags":["timeout","broker-registration","network"],"backgroundTag":"operation-timeout","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}