cannot mix --name for cluster with positional arguments

Error message

cannot mix --name for cluster with positional arguments

What it means

The `kops get clusters` command rejects invocations that pass cluster names as positional arguments while also setting a cluster via the global --name flag. The Args validator in cmd/kops/get_cluster.go enforces this mutual exclusivity because both mechanisms select clusters and combining them is ambiguous. It is a pure argument-validation error raised before any cloud or state-store access.

Source

Thrown at cmd/kops/get_cluster.go:101

	// ClusterNames is a list of cluster names to show; if not specified all clusters will be shown
	ClusterNames []string
}

func NewCmdGetCluster(f *util.Factory, out io.Writer, getOptions *GetOptions) *cobra.Command {
	options := GetClusterOptions{
		GetOptions: getOptions,
	}

	cmd := &cobra.Command{
		Use:     "clusters [CLUSTER]...",
		Aliases: []string{"cluster"},
		Short:   getClusterShort,
		Long:    getClusterLong,
		Example: getClusterExample,
		Args: func(cmd *cobra.Command, args []string) error {
			if len(args) != 0 {
				if rootCommand.clusterName != "" {
					return fmt.Errorf("cannot mix --name for cluster with positional arguments")
				}
				options.ClusterNames = append(options.ClusterNames, args...)
			} else if rootCommand.clusterName != "" {
				options.ClusterNames = append(options.ClusterNames, rootCommand.clusterName)
			}

			return nil
		},
		ValidArgsFunction: commandutils.CompleteClusterName(f, false, true),
		RunE: func(cmd *cobra.Command, args []string) error {
			return RunGetClusters(cmd.Context(), f, out, &options)
		},
	}

	cmd.Flags().BoolVar(&options.FullSpec, "full", options.FullSpec, "Show fully populated configuration")

	return cmd
}

View on GitHub (pinned to 4c8573c808)

Solutions

Remove the positional cluster names and rely only on --name: `kops get clusters --name mycluster.example.com`.
Or drop --name and pass names positionally: `kops get cluster mycluster.example.com`.
Unset KOPS_CLUSTER_NAME in the environment if it was set unintentionally (check with `env | grep KOPS`).

Example fix

// before
kops get clusters --name mycluster.example.com mycluster.example.com
// after
kops get clusters --name mycluster.example.com

Defensive patterns

Strategy: validation

Validate before calling

args="mycluster.example.com"
if [ -n "$KOPS_CLUSTER_NAME" ] && [ -n "$args" ]; then
  echo "Cannot mix --name/KOPS_CLUSTER_NAME with positional cluster args" >&2; exit 1
fi
kops get clusters $args

Type guard

null

Try / catch

null

Prevention

Pick one selection style per invocation: either --name or positional args, never both.
Avoid exporting KOPS_CLUSTER_NAME in long-lived shell profiles; scope it per script.
Wrap kops calls in scripts that check `env | grep KOPS_CLUSTER_NAME` before adding positional names.

When it happens

Trigger: Running e.g. `kops get clusters --name mycluster.example.com mycluster.example.com` or `kops get cluster --name a.example.com b.example.com` — len(args) != 0 and rootCommand.clusterName != "".

Common situations: Scripts that append a cluster name positionally while KOPS_CLUSTER_NAME (or --name) is exported in the environment; users copying examples that use either style but not both; shell aliases that inject --name automatically.

Related errors

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