vitessio/vitess · error

cluster name needs to be provided

Error message

cluster name needs to be provided

What it means

This error is returned by a vtctl cluster-related command handler when no cluster name positional argument is supplied. The surrounding code supports listing clusters (printing joined cluster names and returning early), but if the list path is not taken it requires exactly one argument naming the cluster to operate on. The handler validates NArg() == 1 before branching on --cluster-type (e.g. vitess).

Source

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

	// vitess cluster params
	topoType := subFlags.String("topo_type", "", "Type of cluster's topology server")
	topoServer := subFlags.String("topo_server", "", "Server url of cluster's topology server")
	topoRoot := subFlags.String("topo_root", "", "Root node of cluster's topology")

	if err := subFlags.Parse(args); err != nil {
		return err
	}
	if *list {
		clusters, err := wr.TopoServer().GetExternalVitessClusters(ctx)
		if err != nil {
			return err
		}
		wr.Logger().Printf("%s\n", strings.Join(clusters, ","))
		return nil
	}
	if subFlags.NArg() != 1 {
		return errors.New("cluster name needs to be provided")
	}

	clusterName := subFlags.Arg(0)
	switch *clusterType {
	case "vitess":
		switch {
		case *unmount:
			return wr.UnmountExternalVitessCluster(ctx, clusterName)
		case *show:
			vci, err := wr.TopoServer().GetExternalVitessCluster(ctx, clusterName)
			if err != nil {
				return err
			}
			if vci == nil {
				return fmt.Errorf("there is no vitess cluster named %s", clusterName)
			}
			data, err := json.Marshal(vci)
			if err != nil {

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Re-run providing exactly one cluster name: e.g. `vtctl <command> --cluster-type vitess mycluster`.
2. Verify the cluster name matches a configured cluster.
3. If you intended to list clusters, use the list invocation (no positional args) rather than passing a partial command.
4. Check the command's --help for the list-vs-act usage.

Example fix

// before
vtctl AddCluster --cluster-type vitess
// after
vtctl AddCluster --cluster-type vitess mycluster

cluster="mycluster"
if [ -z "$cluster" ] || [ $# -ne 1 ]; then
  echo "usage: vtctl <cluster command> --cluster-type <type> <cluster name>" >&2
  exit 2
fi
vtctl "$command" --cluster-type vitess "$cluster"

out, err := exec.Command("vtctl", cmd, "--cluster-type", "vitess", cluster).CombinedOutput()
if err != nil {
    if strings.Contains(string(out), "cluster name needs to be provided") {
        return fmt.Errorf("cluster command requires exactly one cluster-name positional arg")
    }
    return err
}

When it happens

Trigger: Running the cluster command (e.g. with --cluster-type vitess) without the cluster name positional argument, or with more than one positional argument (NArg() != 1).

Common situations: Omitting the cluster name while setting --cluster-type; scripts where the cluster name variable is empty; confusing the flag-based type with the positional name and passing both as flags.

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/edd5c9a53f41ddcd. Report an issue: GitHub.