kubesphere/kubesphere · error

failed to fetch cluster: %s

Error message

failed to fetch cluster: %s

What it means

After resolving the user's granted clusters annotation, ListClusters fetches each granted cluster via resourceGetter. NotFound errors are skipped, but any other retrieval error is wrapped as 'failed to fetch cluster: %s'. This means a granted cluster reference could not be read for a non-not-found reason.

Source

Thrown at pkg/models/tenant/tenant.go:548

	if err != nil {
		return nil, fmt.Errorf("failed to describe user: %s", err)
	}

	grantedClustersAnnotation := userDetail.Annotations[iamv1beta1.GrantedClustersAnnotation]
	var grantedClusters sets.Set[string]
	if len(grantedClustersAnnotation) > 0 {
		grantedClusters = sets.New(strings.Split(grantedClustersAnnotation, ",")...)
	} else {
		grantedClusters = sets.New[string]()
	}
	var clusters []*clusterv1alpha1.Cluster
	for _, grantedCluster := range grantedClusters.UnsortedList() {
		obj, err := t.resourceGetter.Get(clusterv1alpha1.ResourcesPluralCluster, "", grantedCluster)
		if err != nil {
			if errors.IsNotFound(err) {
				continue
			}
			return nil, fmt.Errorf("failed to fetch cluster: %s", err)
		}
		cluster := obj.(*clusterv1alpha1.Cluster)
		clusters = append(clusters, cluster)
	}

	items := make([]runtime.Object, 0)
	for _, cluster := range clusters {
		items = append(items, cluster)
	}

	clusterByRoleBinding := false
	if v, ok := queryParam.Filters[queryRoleBindingExists]; ok && v != "" {
		clusterByRoleBinding, err = strconv.ParseBool(string(v))
		if err != nil {
			return nil, err
		}
	}

View on GitHub (pinned to 04a29b5c60)

Solutions

1. Check the wrapped error to identify whether it's timeouts, RBAC, or cache issues
2. Clean up stale cluster names in the user's GrantedClustersAnnotation if clusters were deleted
3. Verify cluster CRs are healthy: `kubectl get cluster` and check agent connectivity for each cluster
4. Restart kubesphere-apiserver to refresh informer caches if reads fail transiently

var cl clusterv1alpha1.ClusterList
if err := k8sClient.List(ctx, &cl); err != nil {
    return fmt.Errorf("cluster resources unreadable: %w", err)
}

func isFetchClusterFailure(err error) bool {
    return err != nil && strings.HasPrefix(err.Error(), "failed to fetch cluster: ")
}

clusters, err := tenant.ListClusters(user, qp)
if err != nil {
    if isFetchClusterFailure(err) {
        return degradedClusterList(qp) // serve partial data with a warning
    }
    return err
}

When it happens

Trigger: Iterating granted cluster names from the user's GrantedClustersAnnotation when the cluster resource Get fails with an error other than NotFound — API server errors, permission failures at the resource layer, or informer cache errors.

Common situations: GrantedClustersAnnotation referencing clusters in a broken multi-cluster setup (host unable to reach agent clusters); cached informer out of sync after cluster deletion/recreation race; RBAC preventing the operator's own read of the cluster resource.

Related errors

• update kubeconfig of the host cluster is not allowed
• update kubeconfig of member clusters which using proxy mode
• unable validate kubesphere endpoint, %v
• failed to validate member cluster configuration, err: %v
• this kubeconfig corresponds to a different cluster than the

AI-assisted analysis of kubesphere/kubesphere@04a29b5c60 (2026-09-03). Data as JSON: /api/errors/e4fc21db87d456f8. Report an issue: GitHub.