kubernetes/kops · error

expected a single <clustername> to be passed as an argument

Error message

expected a single <clustername> to be passed as an argument

What it means

ProcessArgs' final error: more than one positional argument was supplied where at most one (<clustername>) is allowed. Before returning, kops prints all received arguments and the common boolean-flag pitfall (`--bastion true` vs `--bastion=true`). This guards against silently misinterpreting extra tokens as cluster names.

Source

Thrown at cmd/kops/root.go:305

			return nil
		}
	}

	fmt.Printf("\nFound multiple arguments which look like a cluster name\n")
	if c.clusterName != "" {
		fmt.Printf("\t%q (via flag)\n", c.clusterName)
	}
	for _, arg := range args {
		fmt.Printf("\t%q (as argument)\n", arg)
	}
	fmt.Printf("\n")
	fmt.Printf("This often happens if you specify an argument to a boolean flag without using =\n")
	fmt.Printf("For example: use `--bastion=true` or `--bastion`, not `--bastion true`\n\n")

	if len(args) == 1 {
		return fmt.Errorf("cannot specify cluster via --name and positional argument")
	}
	return fmt.Errorf("expected a single <clustername> to be passed as an argument")
}

func (c *RootCmd) ClusterName(verbose bool) string {
	if c.clusterName != "" {
		return c.clusterName
	}

	// Read from kubeconfig
	pathOptions := clientcmd.NewDefaultPathOptions()

	config, err := pathOptions.GetStartingConfig()
	if err != nil {
		klog.Warningf("error reading kubecfg: %v", err)
	} else if config.CurrentContext == "" {
		klog.Warningf("no context set in kubecfg")
	} else {
		context := config.Contexts[config.CurrentContext]
		if context == nil {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Reduce to a single positional <clustername> (or use --name and no positional args)
2. For boolean flags use `--flag=true` syntax so the value is not parsed as a positional argument
3. Quote strings containing spaces so they don't split into multiple args
4. Echo the command in scripts to verify what tokens are actually being passed

Example fix

// before
kops update cluster --bastion yes mycluster.k8s.local
// error: expected a single <clustername> to be passed as an argument
// after
kops update cluster mycluster.k8s.local --bastion=true

// precheck argument count before invoking kops
if len(args) > 1 {
    return fmt.Errorf("kops accepts at most one positional <clustername>; got %d: %v", len(args), args)
}

When it happens

Trigger: The command receives len(args) >= 2, e.g. `kops delete cluster a.k8s.local extra`, or a boolean flag consumed a value leaving multiple stray tokens as positional args (e.g. `kops update cluster --bastion yes a.k8s.local`).

Common situations: Accidentally passing multiple cluster names; unquoted strings with spaces becoming multiple args; `--flag value` misuse on booleans inserting the value into args; copy-pasted commands with extra tokens.

Related errors

• cannot specify cluster via --name and positional argument
• --name is required
• clientset bound to cluster %q, got cluster %q
• --name is required
• cluster not found %q

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/3b89e53f26719b9c. Report an issue: GitHub.