{"record":{"id":"17d54ce39a9b9b26","repo":"grpc/grpc-go","slug":"child-policy-q-not-registered","errorCode":null,"errorMessage":"child policy %q not registered","messagePattern":"child policy %q not registered","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/xds/balancer/clusterimpl/clusterimpl.go","lineNumber":412,"sourceCode":"\tdefer clientConnUpdateHook()\n\n\tb.mu.Lock()\n\tb.inhibitPickerUpdates = true\n\tb.mu.Unlock()\n\tif b.logger.V(2) {\n\t\tb.logger.Infof(\"Received configuration: %s\", pretty.ToJSON(s.BalancerConfig))\n\t}\n\tnewConfig, ok := s.BalancerConfig.(*LBConfig)\n\tif !ok {\n\t\treturn fmt.Errorf(\"unexpected balancer config with type: %T\", s.BalancerConfig)\n\t}\n\n\t// Need to check for potential errors at the beginning of this function, so\n\t// that on errors, we reject the whole config, instead of applying part of\n\t// it.\n\tbb := balancer.Get(newConfig.ChildPolicy.Name)\n\tif bb == nil {\n\t\treturn fmt.Errorf(\"child policy %q not registered\", newConfig.ChildPolicy.Name)\n\t}\n\n\tif b.xdsClient == nil {\n\t\tc := xdsclient.FromResolverState(s.ResolverState)\n\t\tif c == nil {\n\t\t\treturn balancer.ErrBadResolverState\n\t\t}\n\t\tb.xdsClient = c\n\t}\n\n\txdsConfig := xdsresource.XDSConfigFromResolverState(s.ResolverState)\n\tif xdsConfig == nil {\n\t\tb.logger.Warningf(\"Received balancer config with no xDS config\")\n\t\treturn balancer.ErrBadResolverState\n\t}\n\tclusterCfg := xdsConfig.Clusters[newConfig.Cluster]\n\tclusterUpdate := clusterCfg.Config.Cluster\n\tif err := b.handleSecurityConfig(clusterUpdate.SecurityCfg); err != nil {","sourceCodeStart":394,"sourceCodeEnd":430,"githubUrl":"https://github.com/grpc/grpc-go/blob/03255a9237b6eb32710f6bc4f2de9a675b99fe36/internal/xds/balancer/clusterimpl/clusterimpl.go#L394-L430","documentation":"The cluster_impl balancer looks up the child policy name from its config in the global balancer registry and finds nothing. The child policy is the locality-picking/endpoint-picking balancer (e.g., round_robin, weighted_round_robin) that runs beneath cluster_impl. This error means the specified policy name is unknown to gRPC's balancer registry.","triggerScenarios":"Triggered in cluster_impl's UpdateClientConnState when balancer.Get(newConfig.ChildPolicy.Name) returns nil. The child policy name comes from the cluster resource's LB policy configuration sent by the management server, which was parsed and stored in the cluster_impl LBConfig.","commonSituations":"The management server configures an LB policy (e.g., RING_HASH, LEAST_REQUEST) that the gRPC client build doesn't support or hasn't imported; a typo or unsupported policy name in the xDS cluster resource; the weighted_round_robin balancer is not registered (needs import or recent grpc-go version); using a policy that is gated behind an experimental flag or separate import.","solutions":["Check the child policy name in the error message and verify it is a supported gRPC xDS LB policy (round_robin, weighted_round_robin, ring_hash_experimental, least_request_experimental)","Import the required balancer package (e.g., import _ \"google.golang.org/grpc/balancer/weightedroundrobin\")","Upgrade grpc-go to a version that supports the requested LB policy","Reconfigure the management server to use an LB policy supported by your client version"],"exampleFix":"// before: ring_hash not imported, management server requests it\nimport (\n    _ \"google.golang.org/grpc/xds\"\n)\n// after: import ring_hash balancer\nimport (\n    _ \"google.golang.org/grpc/xds\"\n    _ \"google.golang.org/grpc/balancer/ringhash\"\n)","handlingStrategy":"validation","validationCode":"// Verify all child policies are registered before starting xDS\nfunc areChildPoliciesRegistered(policyNames []string) error {\n    for _, name := range policyNames {\n        if balancer.Get(name) == nil {\n            return fmt.Errorf(\"child policy %q is not registered; import its package\", name)\n        }\n    }\n    return nil\n}\n// Usage: check policies used by your management server's cluster configs","typeGuard":null,"tryCatchPattern":"// The channel enters TRANSIENT_FAILURE for the affected cluster\nif conn.GetState() == connectivity.TransientFailure {\n    // check logs for 'child policy X not registered'\n    // import the missing balancer package\n}","preventionTips":["Import all balancer packages your management server may configure: round_robin, weighted_round_robin, ring_hash, least_request","Document which LB policies your management server uses and ensure client imports match","Test client builds against all LB policies configured on the management server","Keep grpc-go version current for the latest balancer implementations"],"tags":["xds","clusterimpl","balancer-registry","lb-policy","child-policy"],"analyzedSha":"03255a9237b6eb32710f6bc4f2de9a675b99fe36","analyzedAt":"2026-08-07T00:29:34.215Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}