%[1]s: '%[2]s' requires at most %[3]d %[4]s Usage: …

Error message

%[1]s: '%[2]s' requires at most %[3]d %[4]s

Usage:  %[5]s

Run '%[2]s --help' for more information

What it means

Returned by cli.RequiresMaxArgs (required.go:56) when len(args) exceeds the configured maximum. Used by commands that accept a bounded number of positional arguments (e.g. `docker rm NAME...` capped, or commands taking exactly one optional). Message includes the max count and usage.

Solutions

Reduce the positional arguments to at most the documented maximum.
If you need to process many items, loop over them calling the command once per item.
Quote/disable uncontrolled glob expansion in your script.

Example fix

// before: too many positionals
docker rmi img1 img2 img3   # if command configured RequiresMaxArgs(1)

// after: one per invocation
for i in img1 img2 img3; do docker rmi "$i"; done

Defensive patterns

Strategy: validation

Validate before calling

// Cap positionals before invoking
if len(positionalArgs) > maxArgs {
    return fmt.Errorf("at most %d positional args allowed, got %d", maxArgs, len(positionalArgs))
}

Prevention

Loop over many items one-at-a-time instead of batching beyond the cap.
Beware unquoted globs expanding to many files.
Validate arg count in wrapper scripts.

When it happens

Trigger: Invoking a command configured with Args: cli.RequiresMaxArgs(N) with more than N positional arguments, e.g. passing three images to a command that takes one.

Common situations: Glob expansion (`*.tar`) producing more files than expected, copy-pasting multiple values where one is allowed, or trailing junk args from a script.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/a954f13f1895f488. Report an issue: GitHub.

Appendix: source

Thrown at cli/required.go:56

		}
		return fmt.Errorf(
			"%[1]s: '%[2]s' requires at least %[3]d %[4]s\n\nUsage:  %[5]s\n\nSee '%[2]s --help' for more information",
			binName(cmd),
			cmd.CommandPath(),
			minArgs,
			pluralize("argument", minArgs),
			cmd.UseLine(),
		)
	}
}

// RequiresMaxArgs returns an error if there is not at most max args
func RequiresMaxArgs(maxArgs int) cobra.PositionalArgs {
	return func(cmd *cobra.Command, args []string) error {
		if len(args) <= maxArgs {
			return nil
		}
		return fmt.Errorf(
			"%[1]s: '%[2]s' requires at most %[3]d %[4]s\n\nUsage:  %[5]s\n\nRun '%[2]s --help' for more information",
			binName(cmd),
			cmd.CommandPath(),
			maxArgs,
			pluralize("argument", maxArgs),
			cmd.UseLine(),
		)
	}
}

// RequiresRangeArgs returns an error if there is not at least min args and at most max args
func RequiresRangeArgs(minArgs int, maxArgs int) cobra.PositionalArgs {
	return func(cmd *cobra.Command, args []string) error {
		if len(args) >= minArgs && len(args) <= maxArgs {
			return nil
		}
		return fmt.Errorf(
			"%[1]s: '%[2]s' requires at least %[3]d and at most %[4]d %[5]s\n\nUsage:  %[6]s\n\nRun '%[2]s --help' for more information",

View on GitHub (pinned to 4f84911bfe)