vitessio/vitess · error

no vitess cluster found with name %s

Error message

no vitess cluster found with name %s

What it means

Server.OpenExternalVitessClusterServer resolves an external vitess cluster by name via GetExternalVitessCluster. If the lookup succeeds but returns nil, the cluster name does not match any registered external cluster, so this error is returned.

Source

Thrown at go/vt/topo/server.go:390

		cc.conn.Close()
	}
	ts.cellConns = make(map[string]cellConn)
}

func (ts *Server) clearCellAliasesCache() {
	cellsAliases.mu.Lock()
	defer cellsAliases.mu.Unlock()
	cellsAliases.cellsToAliases = make(map[string]string)
}

// OpenExternalVitessClusterServer returns the topo server of the external cluster
func (ts *Server) OpenExternalVitessClusterServer(ctx context.Context, clusterName string) (*Server, error) {
	vc, err := ts.GetExternalVitessCluster(ctx, clusterName)
	if err != nil {
		return nil, err
	}
	if vc == nil {
		return nil, fmt.Errorf("no vitess cluster found with name %s", clusterName)
	}
	var externalTopo *Server
	externalTopo, err = OpenServer(vc.TopoConfig.TopoType, vc.TopoConfig.Server, vc.TopoConfig.Root)
	if err != nil {
		return nil, err
	}
	if externalTopo == nil {
		return nil, fmt.Errorf("unable to open external topo for config %s", clusterName)
	}
	return externalTopo, nil
}

// SetReadOnly is initially ONLY implemented by StatsConn and used in ReadOnlyServer
func (ts *Server) SetReadOnly(readOnly bool) error {
	globalCellConn, ok := ts.globalCell.(*StatsConn)
	if !ok {
		return fmt.Errorf("invalid global cell connection type, expected StatsConn but found: %T", ts.globalCell)
	}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Run vtctldclient GetExternalClusters (or check the topo external clusters key) to list valid names
2. Register the external cluster with vtctldclient AddExternalCluster if missing
3. Correct the cluster name typo in the workflow command/flag
4. Verify you are pointing at the topo where the external cluster was actually registered

Example fix

// before
vtctldclient MoveTables --external-cluster prodClusterA ...  # name not registered
// after
vtctldclient AddExternalCluster prodClusterA "etcd:server1:2379" 
vtctldclient MoveTables --external-cluster prodClusterA ...

clusters, err := ts.GetExternalVitessClusters(ctx)
if err != nil {
    return err
}
if !slices.Contains(clusters, clusterName) {
    return fmt.Errorf("cluster %s not registered; known: %v", clusterName, clusters)
}

externalTS, err := ts.OpenExternalVitessClusterServer(ctx, clusterName)
if err != nil {
    if strings.Contains(err.Error(), "no vitess cluster found") {
        return fmt.Errorf("register the external cluster first: %w", err)
    }
    return err
}

When it happens

Trigger: Calling OpenExternalVitessClusterServer (directly or via MoveTables/workflow command paths like commandVReplicationWorkflow, buildMaterializer, buildTrafficSwitcher) with a cluster name that is not present in the topo's external cluster list (topo key ExternalClusters).

Common situations: Typo in the --external-cluster flag value; external cluster never registered via vtctldclient AddExternalCluster (or the external topo was removed); environment mismatch where the source cluster was registered in a different topo.

Related errors

• found an entry from a previous run for migration id %d in _v
• %w: uid %v is already in use
• %w: no SourceShard with uid %v
• invalid format for external source cluster: %s
• there is no vitess cluster named %s

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