the <tablet alias> argument is required for the RunHealthChe

Error message

the <tablet alias> argument is required for the RunHealthCheck command

What it means

This error is returned by the vtctl commandRunHealthCheck handler when RunHealthCheck does not receive exactly one positional argument. The command requires a <tablet alias> to trigger an immediate health check run on that specific tablet. The handler enforces the argument count before parsing the alias and dispatching the RPC.

Source

Thrown at go/vt/vtctl/vtctl.go:1237

	var cells []string
	if *cellsStr != "" {
		cells = strings.Split(*cellsStr, ",")
	}

	_, err = wr.VtctldServer().RefreshStateByShard(ctx, &vtctldatapb.RefreshStateByShardRequest{
		Keyspace: keyspace,
		Shard:    shard,
		Cells:    cells,
	})
	return err
}

func commandRunHealthCheck(ctx context.Context, wr *wrangler.Wrangler, subFlags *pflag.FlagSet, args []string) error {
	if err := subFlags.Parse(args); err != nil {
		return err
	}
	if subFlags.NArg() != 1 {
		return errors.New("the <tablet alias> argument is required for the RunHealthCheck command")
	}
	tabletAlias, err := topoproto.ParseTabletAlias(subFlags.Arg(0))
	if err != nil {
		return err
	}

	_, err = wr.VtctldServer().RunHealthCheck(ctx, &vtctldatapb.RunHealthCheckRequest{
		TabletAlias: tabletAlias,
	})
	return err
}

func commandSleep(ctx context.Context, wr *wrangler.Wrangler, subFlags *pflag.FlagSet, args []string) error {
	if err := subFlags.Parse(args); err != nil {
		return err
	}
	if subFlags.NArg() != 2 {
		return errors.New("the <tablet alias> and <duration> arguments are required for the Sleep command")

View on GitHub (pinned to 01a25a7d17)

Solutions

Re-run with exactly one alias: `vtctl RunHealthCheck zone1-0000000100`.
Verify the alias is a single token; quote if necessary.
Ensure scripts populate the alias variable before invoking.
Run `vtctl RunHealthCheck --help` to confirm usage.

Example fix

// before
vtctl RunHealthCheck
// after
vtctl RunHealthCheck zone1-0000000100

Defensive patterns

Strategy: validation

Validate before calling

alias="zone1-0000000100"
if [ -z "$alias" ] || [ $# -ne 1 ]; then
  echo "usage: vtctl RunHealthCheck <tablet alias>" >&2
  exit 2
fi
vtctl RunHealthCheck "$alias"

Try / catch

out, err := exec.Command("vtctl", "RunHealthCheck", alias).CombinedOutput()
if err != nil {
    if strings.Contains(string(out), "argument is required for the RunHealthCheck") {
        return fmt.Errorf("RunHealthCheck takes exactly one alias arg")
    }
    return err
}

Prevention

Always include exactly one tablet alias; the command is per-tablet, not cluster-wide.
Check alias variables for emptiness in monitoring scripts.
Keep flags and positional args well separated.
Confirm usage with --help.

When it happens

Trigger: Running `vtctl RunHealthCheck` with zero or multiple positional arguments (NArg() != 1).

Common situations: Assuming the command runs cluster-wide without an alias; empty alias variable in monitoring scripts; extra tokens appended after the alias.

Related errors

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