{"record":{"id":"ca6306aaa951e9f7","repo":"grpc/grpc-go","slug":"balancergroup-unregistered-balancer-name-q","errorCode":null,"errorMessage":"balancergroup: unregistered balancer name %q","messagePattern":"balancergroup: unregistered balancer name %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/balancergroup/balancergroup.go","lineNumber":277,"sourceCode":"\t\tlogger:          opts.Logger,\n\n\t\tdeletedBalancerCache: bc,\n\t\tidToBalancerConfig:   make(map[string]*subBalancerWrapper),\n\t\tscToSubBalancer:      make(map[balancer.SubConn]*subBalancerWrapper),\n\t}\n}\n\n// AddWithClientConn adds a balancer with the given id to the group. The\n// balancer is built with a balancer builder registered with balancerName. The\n// given ClientConn is passed to the newly built balancer instead of the\n// one passed to balancergroup.New().\n//\n// TODO: Get rid of the existing Add() API and replace it with this.\nfunc (bg *BalancerGroup) AddWithClientConn(id, balancerName string, cc balancer.ClientConn) error {\n\tbg.logger.Infof(\"Adding child policy of type %q for child %q\", balancerName, id)\n\tbuilder := balancer.Get(balancerName)\n\tif builder == nil {\n\t\treturn fmt.Errorf(\"balancergroup: unregistered balancer name %q\", balancerName)\n\t}\n\n\t// Store data in static map, and then check to see if bg is started.\n\tbg.outgoingMu.Lock()\n\tdefer bg.outgoingMu.Unlock()\n\tif bg.outgoingClosed {\n\t\treturn fmt.Errorf(\"balancergroup: already closed\")\n\t}\n\tvar sbc *subBalancerWrapper\n\t// Skip searching the cache if disabled.\n\tif bg.deletedBalancerCache != nil {\n\t\tif old, ok := bg.deletedBalancerCache.Remove(id); ok {\n\t\t\tif bg.logger.V(2) {\n\t\t\t\tbg.logger.Infof(\"Removing and reusing child policy of type %q for child %q from the balancer cache\", balancerName, id)\n\t\t\t\tbg.logger.Infof(\"Number of items remaining in the balancer cache: %d\", bg.deletedBalancerCache.Len())\n\t\t\t}\n\n\t\t\tsbc, _ = old.(*subBalancerWrapper)","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/grpc/grpc-go/blob/0c51461d27177d997e14c642fe18c11668fc09a3/internal/balancergroup/balancergroup.go#L259-L295","documentation":"Returned by BalancerGroup.AddWithClientConn when balancer.Get(balancerName) returns nil at balancergroup.go:275-278. The requested balancer name is not registered in the global balancer registry. BalancerGroup uses balancer.Get to look up the builder by name, and if no builder was registered under that name, it cannot construct the sub-balancer.","triggerScenarios":"Calling bg.AddWithClientConn(id, \"some_name\", cc) or bg.Add(id, builder) (which calls AddWithClientConn with builder.Name()) where 'some_name' was never registered via balancer.Register(). For example, passing 'my_custom_lb' without first registering it.","commonSituations":"A custom balancer that was built but never registered with balancer.Register. Using the wrong name string (e.g., 'weighted_round_robin' vs 'weighted-target'). Forgetting to import a balancer package that registers itself in init().","solutions":["Register the balancer before adding it: balancer.Register(yourBuilder) or import the package for its init side effect","Verify the name is registered: if balancer.Get(name) == nil { /* not registered */ }","Use builder.Name() to pass the exact registered name rather than hardcoding a string","Check for typos against the official balancer name constants"],"exampleFix":"// before: name not registered\nbg.AddWithClientConn(\"child-0\", \"my_lb\", cc)\n\n// after: register first\nbalancer.Register(myBuilder)\nbg.AddWithClientConn(\"child-0\", myBuilder.Name(), cc)","handlingStrategy":"validation","validationCode":"// Verify balancer name is registered before calling AddWithClientConn\nfunc safeAdd(bg *balancergroup.BalancerGroup, id, name string, cc balancer.ClientConn) error {\n    if balancer.Get(name) == nil {\n        return fmt.Errorf(\"balancer %q is not registered; import the package first\", name)\n    }\n    return bg.AddWithClientConn(id, name, cc)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Register custom balancers with balancer.Register() before creating the BalancerGroup","Pass builder.Name() rather than hardcoded strings to avoid typos","Import balancer packages for their init() registration side effects"],"tags":["grpc","balancer","balancergroup","registration"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}