vitessio/vitess · error

failed to open external topo: %v

Error message

failed to open external topo: %v

What it means

When the workflow sources from an external (mounted) Vitess cluster, buildMaterializer opens a topo server for that cluster via OpenExternalVitessClusterServer. Failure to open it is wrapped with this message.

Source

Thrown at go/vt/wrangler/materializer.go:1109

	}
	if len(ms.SourceShards) > 0 {
		var targetShards2 []*topo.ShardInfo
		for _, shard := range targetShards {
			if slices.Contains(ms.SourceShards, shard.ShardName()) {
				targetShards2 = append(targetShards2, shard)
			}
		}
		targetShards = targetShards2
	}
	if len(targetShards) == 0 {
		return nil, fmt.Errorf("no target shards specified for workflow %s ", ms.Workflow)
	}

	sourceTs := wr.ts
	if ms.ExternalCluster != "" { // when the source is an external mysql cluster mounted using the Mount command
		externalTopo, err := wr.ts.OpenExternalVitessClusterServer(ctx, ms.ExternalCluster)
		if err != nil {
			return nil, fmt.Errorf("failed to open external topo: %v", err)
		}
		sourceTs = externalTopo
	}
	differentPVs := false
	sourceVSchema, err := sourceTs.GetVSchema(ctx, ms.SourceKeyspace)
	if err != nil {
		return nil, fmt.Errorf("failed to get source keyspace vschema: %v", err)
	}
	differentPVs = primaryVindexesDiffer(ms, sourceVSchema.Keyspace, vschema.Keyspace)

	return &materializer{
		wr:                    wr,
		ms:                    ms,
		targetVSchema:         targetVSchema,
		sourceShards:          sourceShards,
		targetShards:          targetShards,
		isPartial:             isPartial,
		primaryVindexesDiffer: differentPVs,

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Check the mount configuration (vtctldclient GetAllMounts / Show) and re-mount with correct topo server and root.
2. Verify network connectivity and topo server health for the external cluster.
3. Confirm the ExternalCluster name matches a currently mounted cluster; update the workflow if it was renamed.

Example fix

// before: stale mount
// workflow references cluster 'sale' that was unmounted
// after
vtctldclient Mount --topo-type etcd2 --topo-server srv1:2379 --name sale
// then retry the MoveTables with --external-cluster sale

mounts, _ := vtctld.GetAllMounts(ctx)
if !slices.ContainsFunc(mounts, func(m string) bool { return m == externalCluster }) {
  return fmt.Errorf("external cluster %s not mounted", externalCluster)
}

m, err := wr.ts.OpenExternalVitessClusterServer(ctx, cluster)
if err != nil {
  // log full error, verify mount config and topo connectivity, then re-mount
}

When it happens

Trigger: ms.ExternalCluster is set but the external cluster cannot be opened — bad mount config, unreachable topo servers, wrong topo flags, or credentials/connection problems to the external topo.

Common situations: Mount command saved incorrect topo server addresses; external cluster topo is down or network-firewalled; cluster was unmounted or renamed but the workflow still references the old name.

Related errors

• failed to open external topo: %v
• unable to get shards for keyspace: %s, error: %v
• FindTablets(cluster = %s): %w
• DiscoverVTGates(cluster = %s): %w
• failed to discover %ss (cluster %s): %w

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