grpc/grpc-go · error

failed to build priority config: %v

Error message

failed to build priority config: %v

What it means

The buildPriorityConfigJSON function calls buildPriorityConfig to construct the priority/cluster_impl/xds-lb-policy balancer tree from the xDS cluster resources. This error wraps any failure from building that tree. Failures can come from building cluster_impl configs for EDS or LogicalDNS clusters, or assembling aggregate cluster configurations.

Source

Thrown at internal/xds/balancer/cdsbalancer/configbuilder.go:99

// priorities.
//
// The built tree of balancers (see test for the output struct).
//
//	          ┌────────┐
//	          │priority│
//	          └┬──────┬┘
//	           │      │
//	┌──────────▼─┐  ┌─▼──────────┐
//	│cluster_impl│  │cluster_impl│
//	└──────┬─────┘  └─────┬──────┘
//	       │              │
//	┌──────▼─────┐  ┌─────▼──────┐
//	│xDSLBPolicy │  │xDSLBPolicy │ (Locality and Endpoint picking layer)
//	└────────────┘  └────────────┘
func buildPriorityConfigJSON(priorities []*priorityConfig, xdsLBPolicy *internalserviceconfig.BalancerConfig) ([]byte, []resolver.Endpoint, error) {
	pc, endpoints, err := buildPriorityConfig(priorities, xdsLBPolicy)
	if err != nil {
		return nil, nil, fmt.Errorf("failed to build priority config: %v", err)
	}
	ret, err := json.Marshal(pc)
	if err != nil {
		return nil, nil, fmt.Errorf("failed to marshal built priority config struct into json: %v", err)
	}
	return ret, endpoints, nil
}

func buildPriorityConfig(priorities []*priorityConfig, xdsLBPolicy *internalserviceconfig.BalancerConfig) (*priority.LBConfig, []resolver.Endpoint, error) {
	var (
		retConfig    = &priority.LBConfig{Children: make(map[string]*priority.Child)}
		retEndpoints []resolver.Endpoint
	)
	for _, p := range priorities {
		clusterUpdate := p.clusterConfig.Cluster
		switch clusterUpdate.ClusterType {
		case xdsresource.ClusterTypeEDS:
			names, configs, endpoints, err := buildClusterImplConfigForEDS(p.childNameGen, p.clusterConfig, xdsLBPolicy)

View on GitHub (pinned to 03255a9237)

Solutions

1. Enable GRPC_GO_LOG_SEVERITY=info to see the wrapped error with the specific failing cluster and field
2. Verify the cluster resources from the management server are complete and well-formed
3. Check that the xDS LB policy structure matches what the current grpc-go version expects
4. Report as a bug with the cluster resource details if the error occurs on standard configurations

// No direct pre-validation — verify cluster resources are complete
// via xDS management server APIs before deploying service configs

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

When it happens

Trigger: Triggered in configbuilder.go when buildPriorityConfig(priorities, xdsLBPolicy) returns an error. The function iterates over priority configs, each representing a cluster, and builds cluster_impl child configs. Errors arise from buildClusterImplConfigForEDS, buildClusterImplConfigForLogicalDNS, or the outlier detection config conversion step.

Common situations: A cluster resource has a nil or missing required field that the config builder expects; the cluster type is not recognized by the switch statement in buildPriorityConfig; the xDS LB policy has an unexpected structure that causes config building to fail; outlier detection config conversion fails for a specific cluster.

Related errors

• failed to build child policy config: %v
• failed to create child policy of type %s: %v
• failed to marshal built priority config struct into json: %v
• no priority is provided, all priorities are removed
• UpstreamTlsContext in CDS response does not contain a Common

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