{"record":{"id":"d9774b31424dc408","repo":"grpc/grpc-go","slug":"did-not-find-the-cluster-q-in-xdsconfig","errorCode":null,"errorMessage":"did not find the cluster %q in XDSConfig","messagePattern":"did not find the cluster %q in XDSConfig","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/xds/balancer/cdsbalancer/cdsbalancer.go","lineNumber":220,"sourceCode":"\n\t// If the cluster is dynamic and we dont have a subscription yet, create\n\t// one.\n\tif b.lbCfg.IsDynamic && !b.isSubscribed {\n\t\tb.unsubscribe = b.clusterSubscriber.SubscribeToCluster(clusterName)\n\t\tb.isSubscribed = true\n\t\treturn nil\n\t}\n\n\tclusterUpdate, ok := b.clusterConfigs[clusterName]\n\tif !ok {\n\t\t// If the cluster is missing from the config, check if it is dynamic.\n\t\t// For dynamic clusters, the xDS config may be updated before the\n\t\t// corresponding cluster resource is received. This should never occur\n\t\t// for static clusters.\n\t\tif b.lbCfg.IsDynamic {\n\t\t\treturn nil\n\t\t}\n\t\treturn b.annotateErrorWithNodeID(fmt.Errorf(\"did not find the cluster %q in XDSConfig\", clusterName))\n\t}\n\t// If the cluster resource has an error, return the error.\n\tif clusterUpdate.Err != nil {\n\t\treturn clusterUpdate.Err\n\t}\n\treturn b.handleClusterUpdate()\n}\n\n// handleClusterUpdate handles a good XDSConfig update from the xDS resolver.\n// Builds the child policy config and pushes it down.\nfunc (b *cdsBalancer) handleClusterUpdate() error {\n\tclusterName := b.lbCfg.ClusterName\n\tclusterConfig := b.clusterConfigs[clusterName].Config\n\n\tvar newPriorities []*priorityConfig\n\tswitch clusterConfig.Cluster.ClusterType {\n\tcase xdsresource.ClusterTypeEDS, xdsresource.ClusterTypeLogicalDNS:\n\t\tp := b.updatePriorityConfig(clusterName, &clusterConfig)","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/grpc/grpc-go/blob/03255a9237b6eb32710f6bc4f2de9a675b99fe36/internal/xds/balancer/cdsbalancer/cdsbalancer.go#L202-L238","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the cluster name in your service config matches exactly (case-sensitive) the cluster name configured on the xDS management server","Check that the CDS resource for this cluster is actually being sent by the management server and is not in an error state","If this is a timing issue during startup, consider using dynamic clusters (isDynamic=true) which tolerate the cluster not being present yet","Inspect the xDS node ID in the error to confirm you are talking to the correct management server","Use xDS logs (GRPC_GO_LOG_SEVERITY=info) to see what cluster resources were actually received"],"exampleFix":"// before: service config references a cluster not on the server\n{\"loadBalancingConfig\": [{\"cds_experimental\": {\"cluster\": \"wrong_cluster_name\", \"isDynamic\": false}}]}\n// after: cluster name matches the CDS resource name\n{\"loadBalancingConfig\": [{\"cds_experimental\": {\"cluster\": \"correct_cluster_name\", \"isDynamic\": false}}]}","handlingStrategy":"validation","validationCode":"// Before relying on a cluster, verify it exists in the xDS config\n// This is done implicitly by the balancer; for proactive checks:\n// List available clusters from your xDS management server API\n// and cross-reference with service config cluster names","typeGuard":null,"tryCatchPattern":"// Handle the error from the channel's connectivity state:\nconn.WaitForStateChange(ctx, connectivity.Ready)\nif conn.GetState() == connectivity.TransientFailure {\n    // check xDS logs for 'did not find the cluster' errors\n    // verify cluster name matches management server config\n}","preventionTips":["Use dynamic clusters (isDynamic=true) when the cluster resource may arrive after the service config","Cross-reference cluster names in the service config with CDS resource names on the management server","Use consistent naming conventions for clusters across LDS/RDS/CDS configurations","Set GRPC_GO_LOG_SEVERITY=info to catch cluster resolution issues early"],"tags":["xds","cds","config","cluster","resource-not-found"],"analyzedSha":"03255a9237b6eb32710f6bc4f2de9a675b99fe36","analyzedAt":"2026-08-07T00:29:34.215Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}