{"record":{"id":"05579636e69ab14b","repo":"vitessio/vitess","slug":"the-keyspace-shard-argument-is-required-for-the","errorCode":null,"errorMessage":"the <keyspace/shard> argument is required for the RefreshStateByShard command","messagePattern":"the <keyspace/shard> argument is required for the RefreshStateByShard command","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/vt/vtctl/vtctl.go","lineNumber":1211,"sourceCode":"\t}\n\ttabletAlias, err := topoproto.ParseTabletAlias(subFlags.Arg(0))\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t_, err = wr.VtctldServer().RefreshState(ctx, &vtctldatapb.RefreshStateRequest{\n\t\tTabletAlias: tabletAlias,\n\t})\n\treturn err\n}\n\nfunc commandRefreshStateByShard(ctx context.Context, wr *wrangler.Wrangler, subFlags *pflag.FlagSet, args []string) error {\n\tcellsStr := subFlags.String(\"cells\", \"\", \"Specifies a comma-separated list of cells whose tablets are included. If empty, all cells are considered.\")\n\tif err := subFlags.Parse(args); err != nil {\n\t\treturn err\n\t}\n\tif subFlags.NArg() != 1 {\n\t\treturn errors.New(\"the <keyspace/shard> argument is required for the RefreshStateByShard command\")\n\t}\n\n\tkeyspace, shard, err := topoproto.ParseKeyspaceShard(subFlags.Arg(0))\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tvar cells []string\n\tif *cellsStr != \"\" {\n\t\tcells = strings.Split(*cellsStr, \",\")\n\t}\n\n\t_, err = wr.VtctldServer().RefreshStateByShard(ctx, &vtctldatapb.RefreshStateByShardRequest{\n\t\tKeyspace: keyspace,\n\t\tShard:    shard,\n\t\tCells:    cells,\n\t})\n\treturn err","sourceCodeStart":1193,"sourceCodeEnd":1229,"githubUrl":"https://github.com/vitessio/vitess/blob/01a25a7d176f94613b8d59d799f438380a8760e4/go/vt/vtctl/vtctl.go#L1193-L1229","documentation":"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.","triggerScenarios":"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).","commonSituations":"Passing `commerce 0` instead of `commerce/0` (which yields NArg()==2); omitting the argument entirely; scripts with an unset keyspace/shard variable.","solutions":["Re-run with a single slash-separated value: `vtctl RefreshStateByShard commerce/0`.","If filtering by cell, use the flag form: `vtctl RefreshStateByShard -cells zone1 commerce/0`.","Do not split keyspace and shard into two positional args.","Check `vtctl RefreshStateByShard --help`."],"exampleFix":"// before\nvtctl RefreshStateByShard commerce 0\n// after\nvtctl RefreshStateByShard commerce/0","handlingStrategy":"validation","validationCode":"ks=\"commerce/0\"\ncase \"$ks\" in\n  */*) ;;\n  *) echo \"usage: vtctl RefreshStateByShard <keyspace/shard>\" >&2; exit 2 ;;\nesac\nvtctl RefreshStateByShard \"$ks\"","typeGuard":null,"tryCatchPattern":"out, err := exec.Command(\"vtctl\", \"RefreshStateByShard\", keyspaceShard).CombinedOutput()\nif err != nil {\n    if strings.Contains(string(out), \"argument is required for the RefreshStateByShard\") {\n        return fmt.Errorf(\"pass keyspace and shard as ONE arg: keyspace/shard\")\n    }\n    return err\n}","preventionTips":["Pass keyspace and shard as one slash-separated token (commerce/0), never two args.","Use the -cells flag for cell filtering, not extra positional args.","Validate the argument contains a slash before invoking.","Quote the keyspace/shard token in scripts."],"tags":["vtctl","cli","missing-argument","keyspace-shard"],"backgroundTag":"missing-required-cli-argument","analyzedSha":"01a25a7d176f94613b8d59d799f438380a8760e4","analyzedAt":"2026-09-01T17:28:30.605Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}