%[1]s: '%[2]s' requires %[3]d %[4]s Usage: %[5]s Run…

Error message

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

Usage:  %[5]s

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

What it means

Returned by cli.ExactArgs (required.go:91) when len(args) is not exactly the required number. Used by commands needing a precise count of positional arguments (e.g. exactly 2 for tag/push-with-dest). The message states the exact number, pluralized, plus usage.

Solutions

Provide exactly N positional arguments as printed.
Confirm required vs optional positionals via `<cmd> --help`.
Validate argument count in your wrapper script before invoking docker.

Example fix

// before: wrong count for ExactArgs(2)
docker tag src dst extra

// after: exactly two
docker tag src dst

Defensive patterns

Strategy: validation

Validate before calling

// Require exact count before invoking
if len(positionalArgs) != exact {
    return fmt.Errorf("need exactly %d positional args, got %d", exact, len(positionalArgs))
}

Prevention

Map out required-vs-optional positionals from --help.
Make wrapper scripts assert arg count before calling docker.
Avoid trailing tokens that inflate the count.

When it happens

Trigger: Invoking a command configured with Args: cli.ExactArgs(N) with any count other than N positional arguments.

Common situations: Dropping one of a pair of required args, adding an extra trailing arg, or a script conditionally omitting an argument.

Related errors

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

Appendix: source

Thrown at cli/required.go:91

		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",
			binName(cmd),
			cmd.CommandPath(),
			minArgs,
			maxArgs,
			pluralize("argument", maxArgs),
			cmd.UseLine(),
		)
	}
}

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

// binName returns the name of the binary / root command (usually 'docker').
func binName(cmd *cobra.Command) string {
	return cmd.Root().Name()
}

//nolint:unparam
func pluralize(word string, number int) string {
	if number == 1 {

View on GitHub (pinned to 4f84911bfe)