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

Error message

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

Usage:  %[5]s

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

What it means

Returned by cli.RequiresMinArgs (required.go:39) when len(args) is below the configured minimum. It is a cobra PositionalArgs validator used by commands that need at least N positional arguments (e.g. `docker tag SRC DST`). Message includes min count, pluralized word, command path, and usage.

Solutions

Re-read the usage line printed and supply the missing positional argument(s).
If a variable was empty and got dropped, quote it or default it.
Run `<cmd> --help` to confirm the required positional count.

Example fix

// before: missing destination
docker tag myimage

// after: both source and destination
docker tag myimage myimage:latest

Defensive patterns

Strategy: validation

Validate before calling

// Ensure at least min args before calling
if len(positionalArgs) < minArgs {
    return fmt.Errorf("need at least %d positional args, got %d", minArgs, len(positionalArgs))
}

Prevention

Read --help to learn the required positional count.
Guard scripts for empty variables that expand to missing args.
Use `set -u` to catch unset variables.

When it happens

Trigger: Invoking a command configured with Args: cli.RequiresMinArgs(N) with fewer than N positional arguments, e.g. `docker tag only-one` (requires 2).

Common situations: Forgetting the destination argument, piping that consumes an expected arg, shell expansion that produced fewer tokens than expected, or misreading docs.

Related errors

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

Appendix: source

Thrown at cli/required.go:39

			cmd.UseLine(),
		)
	}

	return fmt.Errorf(
		"%[1]s: '%[2]s' accepts no arguments\n\nUsage:  %[3]s\n\nRun '%[2]s --help' for more information",
		binName(cmd),
		cmd.CommandPath(),
		cmd.UseLine(),
	)
}

// RequiresMinArgs returns an error if there is not at least min args
func RequiresMinArgs(minArgs int) cobra.PositionalArgs {
	return func(cmd *cobra.Command, args []string) error {
		if len(args) >= minArgs {
			return nil
		}
		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",

View on GitHub (pinned to 4f84911bfe)