grpc/grpc-go · error

failed to build child policy config: %v

Error message

failed to build child policy config: %v

What it means

The CDS balancer calls buildPriorityConfigJSON() to construct the child policy configuration from priority configs and the xDS LB policy. This error wraps any failure from that function, which builds a tree of cluster_impl balancers under a priority balancer. The underlying error could come from building cluster_impl configs for EDS, LogicalDNS, or aggregate cluster types.

Source

Thrown at internal/xds/balancer/cdsbalancer/cdsbalancer.go:280

}

// updateChildConfig builds child policy configuration using endpoint addresses
// returned from the XDSConfig and child policy configuration.
//
// A child policy is created if one doesn't already exist. The newly built
// configuration is then pushed to the child policy.
func (b *cdsBalancer) updateChildConfig() error {
	if b.childLB == nil {
		childLB, err := newChildBalancer(b.cc, b.bOpts)
		if err != nil {
			return fmt.Errorf("failed to create child policy of type %s: %v", priority.Name, err)
		}
		b.childLB = childLB
	}

	childCfgBytes, endpoints, err := buildPriorityConfigJSON(b.priorities, &b.xdsLBPolicy)
	if err != nil {
		return fmt.Errorf("failed to build child policy config: %v", err)
	}
	childCfg, err := b.childConfigParser.ParseConfig(childCfgBytes)
	if err != nil {
		return fmt.Errorf("failed to parse child policy config. This should never happen because the config was generated: %v", err)
	}
	if b.logger.V(2) {
		b.logger.Infof("Built child policy config: %s", pretty.ToJSON(childCfg))
	}

	for i := range endpoints {
		for j := range endpoints[i].Addresses {
			addr := endpoints[i].Addresses[j]
			addr.BalancerAttributes = endpoints[i].Attributes
			// BalancerAttributes are used for the following:
			// * Authority Override.
			// * grpc.lb.backend_service metric label propagation.
			// See https://github.com/grpc/grpc-go/issues/6472
			endpoints[i].Addresses[j] = addr

View on GitHub (pinned to 03255a9237)

Solutions

1. Enable GRPC_GO_LOG_SEVERITY=info to see the wrapped error from buildPriorityConfigJSON that reveals the specific failing cluster
2. Verify all cluster resources referenced by the CDS balancer have valid and supported cluster types (EDS, LogicalDNS, Aggregate)
3. Check for version compatibility between your grpc-go and the management server's resource format
4. Report as a bug with full logs if the error occurs on standard cluster configurations

// No direct pre-validation — verify cluster resources are well-formed
// via the xDS client debug APIs before relying on them

// Monitor for TRANSIENT_FAILURE after xDS config updates
if conn.GetState() == connectivity.TransientFailure {
    // check logs for 'failed to build child policy config' with wrapped error
}

When it happens

Trigger: Triggered in updateChildConfig() when buildPriorityConfigJSON(b.priorities, &b.xdsLBPolicy) returns an error. The function iterates over priorities, builds cluster_impl configs for each, and assembles them into a priority LB config structure. Failures come from buildClusterImplConfigForEDS, buildClusterImplConfigForLogicalDNS, or aggregate cluster handling.

Common situations: A cluster resource has an unsupported or unrecognized cluster type; internal struct building encounters a nil pointer or missing required field in the cluster config; aggregate cluster references leaf clusters with invalid configurations; the xDS LB policy struct is in an unexpected state.

Related errors

• failed to build priority config: %v
• no priority is provided, all priorities are removed
• UpstreamTlsContext in CDS response does not contain a Common
• xds: unable to unmarshal lbconfig: %s, error: %v
• did not find the cluster %q in XDSConfig

AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07). Data as JSON: /api/errors/6106fa22375a584f. Report an issue: GitHub.