vitessio/vitess · error

the <keyspace/shard> argument is required for the RefreshSta

Error message

the <keyspace/shard> argument is required for the RefreshStateByShard command

What it means

This error is raised by the vtctl commandRefreshStateByShard handler when RefreshStateByShard is not given exactly one positional argument. The command requires a single <keyspace/shard> identifier (e.g. commerce/0) to refresh the state of all tablets in that shard, optionally filtered by the --cells flag. The handler validates NArg() == 1 before parsing the keyspace and shard.

Source

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

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

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

func commandRefreshStateByShard(ctx context.Context, wr *wrangler.Wrangler, subFlags *pflag.FlagSet, args []string) error {
	cellsStr := subFlags.String("cells", "", "Specifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered.")
	if err := subFlags.Parse(args); err != nil {
		return err
	}
	if subFlags.NArg() != 1 {
		return errors.New("the <keyspace/shard> argument is required for the RefreshStateByShard command")
	}

	keyspace, shard, err := topoproto.ParseKeyspaceShard(subFlags.Arg(0))
	if err != nil {
		return err
	}

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

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

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Re-run with a single slash-separated value: `vtctl RefreshStateByShard commerce/0`.
2. If filtering by cell, use the flag form: `vtctl RefreshStateByShard -cells zone1 commerce/0`.
3. Do not split keyspace and shard into two positional args.
4. Check `vtctl RefreshStateByShard --help`.

Example fix

// before
vtctl RefreshStateByShard commerce 0
// after
vtctl RefreshStateByShard commerce/0

ks="commerce/0"
case "$ks" in
  */*) ;;
  *) echo "usage: vtctl RefreshStateByShard <keyspace/shard>" >&2; exit 2 ;;
esac
vtctl RefreshStateByShard "$ks"

out, err := exec.Command("vtctl", "RefreshStateByShard", keyspaceShard).CombinedOutput()
if err != nil {
    if strings.Contains(string(out), "argument is required for the RefreshStateByShard") {
        return fmt.Errorf("pass keyspace and shard as ONE arg: keyspace/shard")
    }
    return err
}

When it happens

Trigger: Running `vtctl RefreshStateByShard` with zero arguments or with more than one positional argument (e.g. keyspace and shard passed as separate args instead of keyspace/shard).

Common situations: Passing `commerce 0` instead of `commerce/0` (which yields NArg()==2); omitting the argument entirely; scripts with an unset keyspace/shard variable.

Related errors

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

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