{"record":{"id":"7b72ae12e0d5e894","repo":"grpc/grpc-go","slug":"rls-invalid-childpolicy-entry-v-does-not-contai","errorCode":null,"errorMessage":"rls: invalid childPolicy: entry %v does not contain exactly 1 policy/config pair: %q","messagePattern":"rls: invalid childPolicy: entry (.+?) does not contain exactly 1 policy/config pair: %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"balancer/rls/config.go","lineNumber":287,"sourceCode":"\t\tcacheSizeBytes = maxCacheSize\n\t}\n\treturn &lbConfig{\n\t\tkbMap:                kbMap,\n\t\tlookupService:        lookupService,\n\t\tlookupServiceTimeout: lookupServiceTimeout,\n\t\tmaxAge:               maxAge,\n\t\tstaleAge:             staleAge,\n\t\tcacheSizeBytes:       cacheSizeBytes,\n\t\tdefaultTarget:        rlsProto.GetDefaultTarget(),\n\t}, nil\n}\n\n// parseChildPolicyConfigs iterates through the list of child policies and picks\n// the first registered policy and validates its config.\nfunc parseChildPolicyConfigs(childPolicies []map[string]json.RawMessage, targetFieldName string) (string, map[string]json.RawMessage, error) {\n\tfor i, config := range childPolicies {\n\t\tif len(config) != 1 {\n\t\t\treturn \"\", nil, fmt.Errorf(\"rls: invalid childPolicy: entry %v does not contain exactly 1 policy/config pair: %q\", i, config)\n\t\t}\n\n\t\tvar name string\n\t\tvar rawCfg json.RawMessage\n\t\tfor name, rawCfg = range config {\n\t\t}\n\t\tbuilder := balancer.Get(name)\n\t\tif builder == nil {\n\t\t\tcontinue\n\t\t}\n\t\tparser, ok := builder.(balancer.ConfigParser)\n\t\tif !ok {\n\t\t\treturn \"\", nil, fmt.Errorf(\"rls: childPolicy %q with config %q does not support config parsing\", name, string(rawCfg))\n\t\t}\n\n\t\t// To validate child policy configs we do the following:\n\t\t// - unmarshal the raw JSON bytes of the child policy config into a map\n\t\t// - add an entry with key set to `target_field_name` and a dummy value","sourceCodeStart":269,"sourceCodeEnd":305,"githubUrl":"https://github.com/grpc/grpc-go/blob/0c51461d27177d997e14c642fe18c11668fc09a3/balancer/rls/config.go#L269-L305","documentation":"Emitted from parseChildPolicyConfigs (config.go:287) when a childPolicy array entry (a map[string]json.RawMessage) does not have exactly one key. Each entry must be a single {policyName: config} pair so the balancer can deterministically pick the policy.","triggerScenarios":"A childPolicy entry is an empty object {}, or an object with two or more policy keys like {\"round_robin\":{}, \"pick_first\":{}}.","commonSituations":"Hand-authored config bundling fallback policies in one map entry instead of separate array entries; JSON merge of policy overrides producing multi-key entries; misunderstanding the childPolicy grammar (array of single-key maps, not a single multi-key map).","solutions":["Express each candidate policy as its own array entry: [{\"round_robin\":{}},{\"pick_first\":{}}]. The balancer picks the first registered one.","Remove empty {} entries from the childPolicy array.","Validate the childPolicy shape programmatically before applying (each element must have len == 1)."],"exampleFix":"// before\n\"childPolicy\": [ { \"round_robin\": {}, \"pick_first\": {} } ]\n\n// after\n\"childPolicy\": [ { \"round_robin\": {} }, { \"pick_first\": {} } ]","handlingStrategy":"validation","validationCode":"func validateChildPolicyEntries(policies []map[string]json.RawMessage) error {\n    for i, e := range policies {\n        if len(e) != 1 {\n            return fmt.Errorf(\"childPolicy[%d] must have exactly one policy/config pair, got %d\", i, len(e))\n        }\n    }\n    return nil\n}","typeGuard":"func childPolicyEntriesAreSingleKey(policies []map[string]json.RawMessage) bool {\n    for _, e := range policies {\n        if len(e) != 1 {\n            return false\n        }\n    }\n    return true\n}","tryCatchPattern":null,"preventionTips":["Remember childPolicy is an array of single-key objects, not one multi-key object.","List fallback candidates as separate array entries.","Lint the childPolicy shape in CI."],"tags":["rls","child-policy","validation","service-config"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}