vitessio/vitess · error · errors.ErrUnsupportedCluster

%w: no cluster with id %s

Error message

%w: no cluster with id %s

What it means

Returned by API.getClusterForRequest when the supplied cluster id is not present in vtadmin's in-memory clusterMap. The error wraps errors.ErrUnsupportedCluster so callers can detect it via errors.Is. It means vtadmin was not configured to serve this cluster, not that the cluster is down.

Source

Thrown at go/vt/vtadmin/api.go:2876

	if !api.authz.IsAuthorized(ctx, req.ClusterId, rbac.WorkflowResource, rbac.CreateAction) {
		return nil, fmt.Errorf("%w: cannot switch traffic for workflow in %s", errors.ErrUnauthorized, req.ClusterId)
	}

	c, err := api.getClusterForRequest(req.ClusterId)
	if err != nil {
		return nil, err
	}

	return c.Vtctld.WorkflowSwitchTraffic(ctx, req.Request)
}

func (api *API) getClusterForRequest(id string) (*cluster.Cluster, error) {
	api.clusterMu.Lock()
	defer api.clusterMu.Unlock()

	c, ok := api.clusterMap[id]
	if !ok {
		return nil, fmt.Errorf("%w: no cluster with id %s", errors.ErrUnsupportedCluster, id)
	}

	return c, nil
}

func (api *API) getClustersForRequest(ids []string) ([]*cluster.Cluster, []string) {
	api.clusterMu.Lock()
	defer api.clusterMu.Unlock()

	if len(ids) == 0 {
		clusterIDs := make([]string, 0, len(api.clusters))

		for k := range api.clusterMap {
			clusterIDs = append(clusterIDs, k)
		}

		return api.clusters, clusterIDs
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify req.ClusterId matches a cluster id listed in the vtadmin startup config (--config clusters)
2. Call the GetClusters endpoint to list the valid cluster ids
3. Correct the cluster id in the calling tool/dashboard config and retry

Example fix

// before
req := &vtadminpb.SwitchTabsRequest{ClusterId: "prodcuster"}
// after
req := &vtadminpb.SwitchTabsRequest{ClusterId: "prodcluster"}

clusters, err := client.GetClusters(ctx, &vtadminpb.GetClustersRequest{})
if err != nil { return err }
valid := map[string]bool{}
for _, c := range clusters.Clusters { valid[c.Id] = true }
if !valid[req.ClusterId] {
    return fmt.Errorf("cluster id %q is not configured in vtadmin", req.ClusterId)
}

c, err := client.GetWorkflow(ctx, req)
if err != nil {
    if errors.Is(err, vtadminerrors.ErrUnsupportedCluster) {
        // refresh cluster list / fix cluster id
        return fmt.Errorf("unknown cluster %q; valid ids: %v", req.ClusterId, listClusterIDs(ctx, client))
    }
    return err
}

When it happens

Trigger: Any API method that calls getClusterForRequest (e.g. WorkflowSwitchTraffic) with a req.ClusterId that does not match a cluster id in the vtadmin config (or an id whose cluster failed to load at startup).

Common situations: Typo in cluster id in client request or dashboard; vtadmin started with a config file that omits the cluster; cluster id renamed in config while clients cache the old id.

Related errors

• unregistered Authenticator implementation
• %w: %s
• failed to execute tablet FQDN template for %+v: %w
• ErrRange
• %w %s

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/d7b0eda66396f0b4. Report an issue: GitHub.