grpc/grpc-go · error

did not find the cluster %q in XDSConfig

Error message

did not find the cluster %q in XDSConfig

What it means

The CDS balancer looked up the cluster name from its load balancing config in the xDSConfig's cluster map and found no entry. For static clusters (isDynamic=false) this is a hard error; for dynamic clusters it silently returns nil (the cluster resource may arrive later). This means the management server's LDS/RDS response references a cluster name that was never delivered via CDS.

Source

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

	// If the cluster is dynamic and we dont have a subscription yet, create
	// one.
	if b.lbCfg.IsDynamic && !b.isSubscribed {
		b.unsubscribe = b.clusterSubscriber.SubscribeToCluster(clusterName)
		b.isSubscribed = true
		return nil
	}

	clusterUpdate, ok := b.clusterConfigs[clusterName]
	if !ok {
		// If the cluster is missing from the config, check if it is dynamic.
		// For dynamic clusters, the xDS config may be updated before the
		// corresponding cluster resource is received. This should never occur
		// for static clusters.
		if b.lbCfg.IsDynamic {
			return nil
		}
		return b.annotateErrorWithNodeID(fmt.Errorf("did not find the cluster %q in XDSConfig", clusterName))
	}
	// If the cluster resource has an error, return the error.
	if clusterUpdate.Err != nil {
		return clusterUpdate.Err
	}
	return b.handleClusterUpdate()
}

// handleClusterUpdate handles a good XDSConfig update from the xDS resolver.
// Builds the child policy config and pushes it down.
func (b *cdsBalancer) handleClusterUpdate() error {
	clusterName := b.lbCfg.ClusterName
	clusterConfig := b.clusterConfigs[clusterName].Config

	var newPriorities []*priorityConfig
	switch clusterConfig.Cluster.ClusterType {
	case xdsresource.ClusterTypeEDS, xdsresource.ClusterTypeLogicalDNS:
		p := b.updatePriorityConfig(clusterName, &clusterConfig)

View on GitHub (pinned to 03255a9237)

Solutions

1. Verify the cluster name in your service config matches exactly (case-sensitive) the cluster name configured on the xDS management server
2. Check that the CDS resource for this cluster is actually being sent by the management server and is not in an error state
3. If this is a timing issue during startup, consider using dynamic clusters (isDynamic=true) which tolerate the cluster not being present yet
4. Inspect the xDS node ID in the error to confirm you are talking to the correct management server
5. Use xDS logs (GRPC_GO_LOG_SEVERITY=info) to see what cluster resources were actually received

Example fix

// before: service config references a cluster not on the server
{"loadBalancingConfig": [{"cds_experimental": {"cluster": "wrong_cluster_name", "isDynamic": false}}]}
// after: cluster name matches the CDS resource name
{"loadBalancingConfig": [{"cds_experimental": {"cluster": "correct_cluster_name", "isDynamic": false}}]}

// Before relying on a cluster, verify it exists in the xDS config
// This is done implicitly by the balancer; for proactive checks:
// List available clusters from your xDS management server API
// and cross-reference with service config cluster names

// Handle the error from the channel's connectivity state:
conn.WaitForStateChange(ctx, connectivity.Ready)
if conn.GetState() == connectivity.TransientFailure {
    // check xDS logs for 'did not find the cluster' errors
    // verify cluster name matches management server config
}

When it happens

Trigger: UpdateClientConnState is called on the CDS balancer, the lbCfg.ClusterName is used to look up b.clusterConfigs[clusterName], and the key doesn't exist. This happens when the xDS resolver delivered an xDSConfig whose Clusters map does not contain the cluster name specified in the CDS service config entry.

Common situations: The cluster name in the service config does not match any CDS resource name on the management server (typo, namespace mismatch); the CDS resource was removed from the management server but the LDS/RDS still references it; the xDS server has not yet sent the CDS resource (timing issue for static clusters); aggregate cluster references a leaf cluster that does not exist.

Related errors

• UpstreamTlsContext in CDS response does not contain a Common
• xds: unable to unmarshal lbconfig: %s, error: %v
• failed to correctly update Outlier Detection config %v
• error unmarshalling xDS LB Policy: %v
• failed to build child policy config: %v

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