docker/cli · error

docker: unknown command: docker %s\n\nRun 'docker --help' fo

Error message

docker: unknown command: docker %s\n\nRun 'docker --help' for more information

What it means

Returned by a cobra stub command registered for an invalid plugin (a plugin binary that failed validation). When DisableFlagParsing is on and the user runs the stub, the RunE returns this formatted 'unknown command' error pointing at docker --help. It is only produced for plugins whose metadata/prefix validation failed, not for genuinely unknown CLI commands.

Source

Thrown at cli-plugins/manager/cobra.go:55

			}
			rootCmd.AddCommand(&cobra.Command{
				Use:                p.Name,
				Short:              p.ShortDescription,
				Hidden:             p.Hidden,
				Run:                func(_ *cobra.Command, _ []string) {},
				Annotations:        annotations,
				DisableFlagParsing: true,
				RunE: func(cmd *cobra.Command, args []string) error {
					flags := rootCmd.PersistentFlags()
					flags.SetOutput(nil)
					if err := flags.Parse(args); err != nil {
						return err
					}
					if flags.Changed("help") {
						cmd.HelpFunc()(rootCmd, args)
						return nil
					}
					return fmt.Errorf("docker: unknown command: docker %s\n\nRun 'docker --help' for more information", cmd.Name())
				},
				ValidArgsFunction: func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
					// Delegate completion to plugin
					cargs := []string{p.Path, cobra.ShellCompRequestCmd, p.Name} //nolint:prealloc // no need to over-complicate things.
					cargs = append(cargs, args...)
					cargs = append(cargs, toComplete)
					origArgs := os.Args
					os.Args = cargs
					defer func() {
						os.Args = origArgs
					}()
					runCommand, runErr := PluginRunCommand(dockerCLI, p.Name, cmd)
					if runErr != nil {
						return nil, cobra.ShellCompDirectiveError
					}
					runErr = runCommand.Run()
					if runErr == nil {
						os.Exit(0) // plugin already rendered complete data

View on GitHub (pinned to 4f84911bfe)

Solutions

1. Run docker --help to confirm the intended command name and spelling.
2. Inspect the plugin with docker info or check its metadata JSON for vendor/schema/prefix issues.
3. Rename the plugin binary to start with the docker- prefix and fix its metadata.
4. Remove the broken plugin from PATH if it is no longer needed.

When it happens

Trigger: Running a command backed by a plugin stub whose Err is set (invalid metadata, schema, vendor, or name conflict), e.g. docker <badplugin> ...

Common situations: A plugin binary on PATH that is misconfigured (missing vendor, wrong schema version, wrong prefix) such that the manager registers it as an invalid stub instead of a working command.

Related errors

• failed to unmarshal hook response (%q): %w
• unable to determine basename of plugin candidate %q
• plugin candidate %q: %w
• plugin candidate %q: does not have %q prefix
• plugin SchemaVersion %q has wrong format: must be <major>.<m

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