vitessio/vitess · error

action InitShardPrimary requires <keyspace/shard> <tablet al

Error message

action InitShardPrimary requires <keyspace/shard> <tablet alias>

What it means

commandInitShardPrimary requires exactly two positional arguments: the keyspace/shard and the tablet alias to be initialized as primary. Any other count yields this usage error before parsing, mirroring the ReparentTablet argument check but with the shard-qualified form.

Source

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

	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
	}
	if subFlags.NArg() != 2 {
		return errors.New("action InitShardPrimary requires <keyspace/shard> <tablet alias>")
	}
	keyspace, shard, err := topoproto.ParseKeyspaceShard(subFlags.Arg(0))
	if err != nil {
		return err
	}
	tabletAlias, err := topoproto.ParseTabletAlias(subFlags.Arg(1))
	if err != nil {
		return err
	}
	return wr.InitShardPrimary(ctx, keyspace, shard, tabletAlias, *force, *waitReplicasTimeout)
}

func commandPlannedReparentShard(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)")
	}

	waitReplicasTimeout := subFlags.Duration("wait_replicas_timeout", topo.RemoteOperationTimeout, "time to wait for replicas to catch up on replication before and after reparenting")

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Invoke with exactly two arguments: `vtctldclient InitShardPrimary <keyspace/shard> <tablet alias>`
2. Add --force if the tablet must be initialized as primary even when it is not currently writable or is already primary
3. Validate shell variables so both arguments are non-empty before invocation

Example fix

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

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

When it happens

Trigger: Running `vtctldclient InitShardPrimary` with zero, one, or three-plus positional args — e.g. omitting the shard, or passing only the tablet alias as with ReparentTablet.

Common situations: Confusing InitShardPrimary's two-arg form with ReparentTablet's one-arg form; empty shell variables dropping an argument.

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 ReparentTablet requires <tablet alias>
• the <cell> argument is required for the UpdateCellInfo comma
• the <cell> argument is required for the DeleteCellInfo comma
• GetCellInfoNames command takes no parameter
• the <cell> argument is required for the GetCellInfo command

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