What causes "action StartReplication requires " in vitessio/vitess?

Re-run with exactly one alias: `vtctl StartReplication zone1-0000000101`.

action StartReplication requires

Error message

action StartReplication requires <tablet alias>

What it means

This error comes from the vtctl commandStartReplication handler when StartReplication is not given exactly one positional argument. StartReplication needs the <tablet alias> of the replica tablet on which to begin replicating from its source. Each vtctl command handler validates its own argument count, so an incorrect count fails immediately before any RPC is issued.

Solutions

Re-run with exactly one alias: `vtctl StartReplication zone1-0000000101`.
Confirm the alias format (cell-uid, e.g. zone1-0000000101) is passed as a single token.
Verify any shell variable interpolating the alias is set and unquoted-empty is avoided.
Consult `vtctl StartReplication --help`.

Example fix

// before
vtctl StartReplication
// after
vtctl StartReplication zone1-0000000101

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

out, err := exec.Command("vtctl", "StartReplication", alias).CombinedOutput()
if err != nil {
    if strings.Contains(string(out), "requires <tablet alias>") {
        return fmt.Errorf("StartReplication needs exactly one alias arg; got argv: %v", os.Args)
    }
    return err
}

Prevention

Pass exactly one positional argument (the tablet alias) — no keyspace, no extra tokens.
Check alias variables for emptiness in automation before calling vtctl.
Keep flags separate from positional args and well-formed.
Validate the alias format (cell-uid) before running.

When it happens

Trigger: Running `vtctl StartReplication` with no arguments or with more than one positional argument. subFlags.NArg() != 1 produces the error.

Common situations: Scripted replication setup where the tablet alias variable is empty; passing extra words like the keyspace alongside the alias; copy-pasting a command line where the alias was dropped.

Related errors

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

Appendix: source

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

	}

	tabletAlias, err := topoproto.ParseTabletAlias(subFlags.Arg(0))
	if err != nil {
		return err
	}
	_, err = wr.VtctldServer().SetWritable(ctx, &vtctldatapb.SetWritableRequest{
		TabletAlias: tabletAlias,
		Writable:    true,
	})
	return err
}

func commandStartReplication(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 StartReplication requires <tablet alias>")
	}

	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 {

View on GitHub (pinned to 01a25a7d17)