vitessio/vitess · error

action StartReplication requires <tablet alias>

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.

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)

Solutions

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

Example fix

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

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

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
}

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

• action StopReplication 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/a2c79db00ed790c8. Report an issue: GitHub.