What causes "can only delete one instance at a time" in kubernetes/kops?

Delete one instance per command invocation.

can only delete one instance at a time

Error message

can only delete one instance at a time

What it means

Argument validation in `kops delete instance`: the command accepts exactly one positional argument (an instance ID or node name), and this guard fires when more than one is given. Batch deletion is not supported through this command.

Source

Thrown at cmd/kops/delete_instance.go:133

	cmd := &cobra.Command{
		Use:     "instance INSTANCE|NODE",
		Short:   deleteInstanceShort,
		Long:    deleteInstanceLong,
		Example: deleteInstanceExample,
		Args: func(cmd *cobra.Command, args []string) error {
			options.ClusterName = rootCommand.ClusterName(true)
			if options.ClusterName == "" {
				return fmt.Errorf("--name is required")
			}

			if len(args) == 0 {
				return fmt.Errorf("must specify ID of instance or name of node to delete")
			}
			options.InstanceID = args[0]

			if len(args) != 1 {
				return fmt.Errorf("can only delete one instance at a time")
			}

			return nil
		},
		ValidArgsFunction: completeInstanceOrNode(f, &options),
		RunE: func(cmd *cobra.Command, args []string) error {
			return RunDeleteInstance(cmd.Context(), f, out, &options)
		},
	}

	cmd.Flags().BoolVar(&options.CloudOnly, "cloudonly", options.CloudOnly, "Perform deletion update without confirming progress with Kubernetes")
	cmd.Flags().BoolVar(&options.Surge, "surge", options.Surge, "Surge by detaching the node from the ASG before deletion")

	cmd.Flags().DurationVar(&options.ValidationTimeout, "validation-timeout", options.ValidationTimeout, "Maximum time to wait for a cluster to validate")
	cmd.Flags().Int32Var(&options.ValidateCount, "validate-count", options.ValidateCount, "Number of times that a cluster needs to be validated after single node update")
	cmd.Flags().DurationVar(&options.PostDrainDelay, "post-drain-delay", options.PostDrainDelay, "Time to wait after draining each node")

	cmd.Flags().BoolVar(&options.FailOnDrainError, "fail-on-drain-error", true, "Fail if draining a node fails")

View on GitHub (pinned to 4c8573c808)

Solutions

Delete one instance per command invocation.
Loop in shell: `for id in $IDS; do kops delete instance "$id" --name ...; done`.
Quote node names containing spaces so they collapse to a single argument.

Example fix

// before
kops delete instance i-0abc i-0def --name cluster.example.com
// after
for id in i-0abc i-0def; do kops delete instance "$id" --name cluster.example.com; done

Defensive patterns

Strategy: validation

Validate before calling

ids := strings.Fields(idList)
if len(ids) != 1 {
    return fmt.Errorf("kops delete instance accepts exactly one ID; got %d", len(ids))
}

Prevention

Quote arguments to avoid word-splitting adding extra args.
Loop over IDs instead of passing multiple positionals.
Validate argument count in wrapper scripts.

When it happens

Trigger: Running `kops delete instance i-123 i-456` or passing extra tokens (e.g. an unquoted node name with spaces or stray flags consumed as args).

Common situations: Scripts looping lists without quoting; users assuming batch deletion is supported.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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