vitessio/vitess · error

action ReparentTablet requires

Error message

action ReparentTablet requires <tablet alias>

What it means

commandReparentTablet enforces exactly one positional argument: the tablet alias to reparent to the primary role. Any other argument count (zero or multiple) is rejected with this usage error before any parsing or RPC happens.

Solutions

1. Invoke with exactly one argument: `vtctldclient ReparentTablet <tablet-alias>` (e.g. zone1-0000000100)
2. If you meant to choose a new primary among candidates, use PlannedReparentShard with keyspace/shard and --new_primary instead
3. Quote or validate shell variables so an empty alias does not collapse the argument count

Example fix

// before
vtctldclient ReparentTablet commerce/0 zone1-0000000100
// after
vtctldclient ReparentTablet zone1-0000000100

args=("$@"); if [ ${#args[@]} -ne 1 ]; then
  echo "usage: vtctldclient ReparentTablet <tablet-alias>" >&2; exit 2
fi

When it happens

Trigger: Running `vtctldclient ReparentTablet` with no arguments, with more than one alias, or with the keyspace/shard mistakenly included as an extra positional arg.

Common situations: Copy-pasting command lines from PlannedReparentShard docs (which use keyspace/shard form); shell variable expansions producing empty or extra arguments.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• action InitShardPrimary requires <keyspace/shard>
• active reparent commands disabled (unset the…
• GetCellInfoNames command takes no parameter
• GetCellsAliases command takes no parameter
• the argument is required for the AddCellsAlias command

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

Appendix: source

Thrown at go/vt/vtctl/reparent.go:79

	addCommand("Shards", command{
		name:   "TabletExternallyReparented",
		method: commandTabletExternallyReparented,
		params: "<tablet alias>",
		help: "Changes metadata in the topology server to acknowledge a shard primary change performed by an external tool. See the Reparenting guide for more information:" +
			"https://vitess.io/docs/user-guides/reparenting/#external-reparenting",
	})
}

func commandReparentTablet(ctx context.Context, wr *wrangler.Wrangler, subFlags *pflag.FlagSet, args []string) error {
	if mysqlctl.DisableActiveReparents {
		return errors.New("active reparent commands disabled (unset the --disable-active-reparents flag to enable)")
	}

	if err := subFlags.Parse(args); err != nil {
		return err
	}
	if subFlags.NArg() != 1 {
		return errors.New("action ReparentTablet requires <tablet alias>")
	}
	tabletAlias, err := topoproto.ParseTabletAlias(subFlags.Arg(0))
	if err != nil {
		return err
	}
	return wr.ReparentTablet(ctx, tabletAlias)
}

func commandInitShardPrimary(ctx context.Context, wr *wrangler.Wrangler, subFlags *pflag.FlagSet, args []string) error {
	if mysqlctl.DisableActiveReparents {
		return errors.New("active reparent commands disabled (unset the --disable-active-reparents flag to enable)")
	}

	force := subFlags.Bool("force", false, "will force the reparent even if the provided tablet is not writable or the shard primary")
	waitReplicasTimeout := subFlags.Duration("wait_replicas_timeout", topo.RemoteOperationTimeout, "time to wait for replicas to catch up in reparenting")
	if err := subFlags.Parse(args); err != nil {
		return err
	}

View on GitHub (pinned to 01a25a7d17)