{"id":"c973e4a7585d38f7","repo":"spf13/cobra","slug":"unknown-command-q-for-q-s","errorCode":null,"errorMessage":"unknown command %q for %q%s","messagePattern":"unknown command %q for %q(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"args.go","lineNumber":36,"sourceCode":"\t\"fmt\"\n\t\"strings\"\n)\n\ntype PositionalArgs func(cmd *Command, args []string) error\n\n// legacyArgs validation has the following behaviour:\n// - root commands with no subcommands can take arbitrary arguments\n// - root commands with subcommands will do subcommand validity checking\n// - subcommands will always accept arbitrary arguments\nfunc legacyArgs(cmd *Command, args []string) error {\n\t// no subcommand, always take args\n\tif !cmd.HasSubCommands() {\n\t\treturn nil\n\t}\n\n\t// root command with subcommands, do subcommand checking.\n\tif !cmd.HasParent() && len(args) > 0 {\n\t\treturn fmt.Errorf(\"unknown command %q for %q%s\", args[0], cmd.CommandPath(), cmd.findSuggestions(args[0]))\n\t}\n\treturn nil\n}\n\n// NoArgs returns an error if any args are included.\nfunc NoArgs(cmd *Command, args []string) error {\n\tif len(args) > 0 {\n\t\treturn fmt.Errorf(\"unknown command %q for %q\", args[0], cmd.CommandPath())\n\t}\n\treturn nil\n}\n\n// OnlyValidArgs returns an error if there are any positional args that are not in\n// the `ValidArgs` field of `Command`\nfunc OnlyValidArgs(cmd *Command, args []string) error {\n\tif len(cmd.ValidArgs) > 0 {\n\t\t// Remove any description that may be included in ValidArgs.\n\t\t// A description is following a tab character.","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/spf13/cobra/blob/adbc8813901bba65827259daa8e22ff94ec1f30e/args.go#L18-L54","documentation":"Thrown by legacyArgs (cobra's default Args validator) when a root command that HAS subcommands receives positional arguments that don't match any subcommand. Cobra treats the first positional arg as a candidate subcommand name; if no child matches, it reports the arg as an 'unknown command' and appends suggestion text (the %s is findSuggestions output, e.g. 'Did you mean this?'). This is the implicit validation applied when you do not set Command.Args.","triggerScenarios":"Running `rootCmd foobar` where rootCmd has subcommands registered via AddCommand but 'foobar' is not one of them. Also triggered by typos in subcommand names, or by passing a flag-like token after `--` to a root that has children (legacyArgs still checks args[0]). Does NOT fire if the command has no subcommands, or if the command is itself a subcommand (HasParent).","commonSituations":"Misspelling a subcommand (`gti status` style typo), renamed subcommands after a library upgrade, hidden/deprecated commands the user expects to exist, or a root command that the developer assumed would accept arbitrary args but actually has children registered.","solutions":["Check the spelled subcommand against the output of `<program> help` or the suggestions Cobra prints (the %s portion lists close matches).","If the root should accept arbitrary positional args even though it has subcommands, set rootCmd.Args = cobra.ArbitraryArgs (or a custom PositionalArgs) to bypass legacyArgs.","Register the intended command as a child via rootCmd.AddCommand(&subCmd) if it was supposed to exist.","If you want unknown subcommand input to route to the root, set the root's Args field explicitly and consider TraverseChildren."],"exampleFix":"// before: root has subcommands, default Args validator\nrootCmd := &cobra.Command{Use: \"app\"}\nrootCmd.AddCommand(serveCmd)\n// `app srve` -> unknown command \"srve\"\n\n// after: accept arbitrary args at root, or fix the typo\nrootCmd.Args = cobra.ArbitraryArgs","handlingStrategy":"validation","validationCode":"// Before Execute, confirm the first positional resolves to a child\nfunc resolveSubcommand(root *cobra.Command, args []string) error {\n    if !root.HasSubCommands() || len(args) == 0 {\n        return nil\n    }\n    target, _, err := root.Find(args)\n    if err != nil || target == root && len(target.Commands()) > 0 {\n        names := []string{}\n        for _, c := range root.Commands() { if c.IsAvailableCommand() { names = append(names, c.Name()) } }\n        return fmt.Errorf(\"no subcommand %q; choose from %v\", args[0], names)\n    }\n    return nil\n}","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Set Command.Args explicitly on every root that has subcommands so behavior is intentional rather than the legacyArgs default.","Surface available subcommands in your own help/usage text so users don't guess.","Use Find() in a pre-run hook to give a clearer message than the default suggestion text."],"tags":["cli","args","subcommand","cobra","validation"],"analyzedSha":"adbc8813901bba65827259daa8e22ff94ec1f30e","analyzedAt":"2026-08-04T21:41:27.617Z","schemaVersion":2}