%[1]s: unknown command: %[2]s %[3]s Usage: %[4]s Run…

Error message

%[1]s: unknown command: %[2]s %[3]s

Usage:  %[4]s

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

What it means

Returned by cli.NoArgs (required.go:16) when the command received positional arguments AND cmd.HasSubCommands() is true. It is the cobra Args validator telling the user the first positional token was not recognized as a subcommand of a command that has subcommands. The format includes the binary name, command path, the offending token, and the usage line.

Solutions

Run `<command path> --help` to list valid subcommands and correct the typo.
Upgrade/downgrade docker to match the subcommand you expect.
Check shell aliases and scripts that prepend arguments.
Quote or reorder arguments so flags come before positional tokens.

Example fix

// before: typo'd subcommand
docker image buld -t x .

// after: correct subcommand
docker image build -t x .

Defensive patterns

Strategy: validation

Validate before calling

// Validate the requested subcommand exists before invoking
cmd, _, e := rootCmd.Find(append([]string{parent}, args...))
if e != nil || cmd == nil || cmd == rootCmd && len(args) > 0 {
    return fmt.Errorf("unknown subcommand %q; see %s --help", args[0], parent)
}

Prevention

Always provide --help discovery for parent commands.
Pin docker versions in scripts to match available subcommands.
Validate subcommand names in wrappers before calling docker.

When it happens

Trigger: A cobra command configured with Args: cli.NoArgs that also defines subcommands receives an unknown first argument — e.g. `docker foo bar` where `foo` has subcommands but `bar` is not one. The validator fires before cobra's own subcommand dispatch message.

Common situations: Typos in subcommand names, using a subcommand from a newer docker version on an older binary, aliasing issues, or scripts passing an unexpected positional token to a parent command.

Related errors

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

Appendix: source

Thrown at cli/required.go:16

package cli

import (
	"fmt"

	"github.com/spf13/cobra"
)

// NoArgs validates args and returns an error if there are any args
func NoArgs(cmd *cobra.Command, args []string) error {
	if len(args) == 0 {
		return nil
	}

	if cmd.HasSubCommands() {
		return fmt.Errorf(
			"%[1]s: unknown command: %[2]s %[3]s\n\nUsage:  %[4]s\n\nRun '%[2]s --help' for more information",
			binName(cmd),
			cmd.CommandPath(),
			args[0],
			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 {

View on GitHub (pinned to 4f84911bfe)