vitessio/vitess · error

invalid tablet alias %q: %v

Error message

invalid tablet alias %q: %v

What it means

Returned by mysqlctl clone logic when the provided tablet alias string is malformed, wrapping the parse error with the offending alias.

Source

Thrown at go/vt/mysqlctl/clone.go:98

		return replication.Position{}, errors.New("--clone-from-primary and --clone-from-tablet are mutually exclusive")
	case cloneFromPrimary:
		// Look up the primary tablet from topology.
		log.Info(fmt.Sprintf("Looking up primary tablet for shard %s/%s for use as CLONE REMOTE donor", keyspace, shard))
		si, err := topoServer.GetShard(ctx, keyspace, shard)
		if err != nil {
			return replication.Position{}, fmt.Errorf("failed to get shard %s/%s: %v", keyspace, shard, err)
		}
		if topoproto.TabletAliasIsZero(si.PrimaryAlias) {
			return replication.Position{}, fmt.Errorf("shard %s/%s has no primary", keyspace, shard)
		}
		donorAlias = si.PrimaryAlias
		log.Info(fmt.Sprintf("Found primary tablet %s for use as CLONE REMOTE donor", topoproto.TabletAliasString(donorAlias)))
	case cloneFromTablet != "":
		// Parse the explicit donor tablet alias.
		log.Info(fmt.Sprintf("Using tablet %s for use as CLONE REMOTE donor", cloneFromTablet))
		donorAlias, err = topoproto.ParseTabletAlias(cloneFromTablet)
		if err != nil {
			return replication.Position{}, fmt.Errorf("invalid tablet alias %q: %v", cloneFromTablet, err)
		}
	default:
		return replication.Position{}, errors.New("no donor specified")
	}

	// Get donor tablet info from topology.
	donorTablet, err := topoServer.GetTablet(ctx, donorAlias)
	if err != nil {
		return replication.Position{}, fmt.Errorf("failed to get tablet %s from topology: %v", topoproto.TabletAliasString(donorAlias), err)
	}

	// Get clone credentials.
	cloneConfig := dbconfigs.GlobalDBConfigs.CloneUser
	if cloneConfig.User == "" {
		return replication.Position{}, errors.New("clone user not configured; set --db-clone-user flag")
	}

	// Create the clone executor.

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Use the exact `<cell>-<uid>` form, e.g. `zone1-0000000100`.
2. Get the correct alias with `vtctldclient GetTablets` and copy it verbatim.
3. Strip surrounding whitespace/quotes from the flag value.

Example fix

// before
--clone-from-tablet=zone1.100
// after
--clone-from-tablet=zone1-0000000100

alias, err := topoproto.ParseTabletAlias(flagCloneFromTablet)
if err != nil {
	return fmt.Errorf("--clone-from-tablet must be cell-uid form like zone1-0000000100: %w", err)
}

if err != nil && strings.Contains(err.Error(), "invalid tablet alias") {
	// correct the alias format and retry
}

When it happens

Trigger: CloneFromDonor invoked with a malformed --clone-from-tablet string (missing cell prefix, non-numeric uid, trailing whitespace, or alias format not matching the topo's alias parsing rules).

Common situations: Typo in tablet alias, using a hostname instead of a tablet alias, copying an alias from the wrong cell format, shell mangling of dashes.

Related errors

• ErrPartSize
• BeforeSchema differs
• AfterSchema differs
• UUID values must be unique
• BaseKeyspace is required for SNAPSHOT keyspaces

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