vitessio/vitess · error

action StopReplication requires <tablet alias>

Error message

action StopReplication requires <tablet alias>

What it means

This error is raised by the vtctl commandStopReplication handler when StopReplication does not receive exactly one positional argument. The command requires a single <tablet alias> to identify the tablet whose replication should be halted. Argument-count validation is done per-command in the handler, so the error fires before any tablet RPC.

Source

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

	}

	tabletAlias, err := topoproto.ParseTabletAlias(subFlags.Arg(0))
	if err != nil {
		return err
	}

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

func commandStopReplication(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("action StopReplication requires <tablet alias>")
	}

	tabletAlias, err := topoproto.ParseTabletAlias(subFlags.Arg(0))
	if err != nil {
		return err
	}

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

func commandChangeTabletType(ctx context.Context, wr *wrangler.Wrangler, subFlags *pflag.FlagSet, args []string) error {
	dryRun := subFlags.Bool("dry-run", false, "Lists the proposed change without actually executing it")

	if err := subFlags.Parse(args); err != nil {
		return err

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Re-run with exactly one alias: `vtctl StopReplication zone1-0000000101`.
2. Ensure no stray tokens follow the alias (flags must come before positional args or be properly formed).
3. Check the alias variable is populated in scripts before invoking vtctl.
4. Run `vtctl StopReplication --help` to confirm usage.

Example fix

// before
vtctl StopReplication
// after
vtctl StopReplication zone1-0000000101

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

out, err := exec.Command("vtctl", "StopReplication", alias).CombinedOutput()
if err != nil {
    if strings.Contains(string(out), "requires <tablet alias>") {
        // inspect argv and retry with exactly one alias
    }
    return err
}

When it happens

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

Common situations: Empty alias variable in automation scripts; accidentally including flags-like extra tokens after the alias; forgetting the alias when manually halting replication during maintenance.

Related errors

• action StartReplication requires <tablet alias>
• the <tablet alias> argument is required for the SetReadWrite
• the <tablet alias> and <db type> arguments are required for
• the <tablet alias> argument is required for the Ping command
• the <tablet alias> argument is required for the RefreshState

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