docker/cli · error

docker: unknown command: docker

Error message

docker: unknown command: docker %s

Run 'docker --help' for more information

What it means

Returned by the root cobra command's RunE in newDockerCommand() when arguments are passed but no subcommand matches (and no plugin provides it). %s is the first (unrecognized) argument. This is docker's standard 'command not found' message directing the user to `docker --help`.

Solutions

1. Check spelling against `docker --help`.
2. If it's a known plugin command (e.g. compose, buildx, scout), install that plugin.
3. Run `docker --help` to enumerate available top-level commands.

Example fix

// before
$ docker bulid .
docker: unknown command: docker bulid

Run 'docker --help' for more information

// after
$ docker build .

// Validate the subcommand exists before running
func commandExists(sub string) (bool, error) {
    out, err := exec.Command("docker", "--help").CombinedOutput()
    if err != nil { return false, err }
    return strings.Contains(string(out), "  "+sub+" "), nil
}

// Treat unknown command as a usage error in wrappers and surface help
out, err := exec.CommandContext(ctx, "docker", sub).CombinedOutput()
if err != nil && strings.Contains(string(out), "unknown command") {
    return fmt.Errorf("invalid docker subcommand %q; see `docker --help`", sub)
}

When it happens

Trigger: Typing a nonexistent subcommand: `docker bulid`, `docker psa`, `docker container lst`, or a plugin command whose plugin is not installed (and the plugin manager fell through to root Execute).

Common situations: Typos; expecting a plugin (buildx, compose, scout) that isn't installed; using a command from a newer/older docker version not present in this build.

Related errors

• unknown help topic
• every ip-range or gateway must have a corresponding subnet
• multiple overlapping subnet configuration is not supported
• network prune has been cancelled
• node ID not found in /info

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

Appendix: source

Thrown at cmd/docker/docker.go:152

}

func newDockerCommand(dockerCli *command.DockerCli) *cli.TopLevelCommand {
	var (
		opts    *cliflags.ClientOptions
		helpCmd *cobra.Command
	)

	cmd := &cobra.Command{
		Use:              "docker [OPTIONS] COMMAND [ARG...]",
		Short:            "A self-sufficient runtime for containers",
		SilenceUsage:     true,
		SilenceErrors:    true,
		TraverseChildren: true,
		RunE: func(cmd *cobra.Command, args []string) error {
			if len(args) == 0 {
				return command.ShowHelp(dockerCli.Err())(cmd, args)
			}
			return fmt.Errorf("docker: unknown command: docker %s\n\nRun 'docker --help' for more information", args[0])
		},
		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
			return isSupported(cmd, dockerCli)
		},
		Version:               fmt.Sprintf("%s, build %s", version.Version, version.GitCommit),
		DisableFlagsInUseLine: true,
		CompletionOptions: cobra.CompletionOptions{
			DisableDefaultCmd:   false,
			HiddenDefaultCmd:    true,
			DisableDescriptions: os.Getenv("DOCKER_CLI_DISABLE_COMPLETION_DESCRIPTION") != "",
		},
	}

	// Disable file-completion by default. Most commands and flags should not
	// complete with filenames.
	cmd.CompletionOptions.SetDefaultShellCompDirective(cobra.ShellCompDirectiveNoFileComp)

	cmd.SetIn(dockerCli.In())

View on GitHub (pinned to 4f84911bfe)