{"record":{"id":"a954f13f1895f488","repo":"docker/cli","slug":"1-s-2-s-requires-at-most-3-d-4-s-usage","errorCode":null,"errorMessage":"%[1]s: '%[2]s' requires at most %[3]d %[4]s\n\nUsage:  %[5]s\n\nRun '%[2]s --help' for more information","messagePattern":"%\\[1\\]s: '%\\[2\\]s' requires at most %\\[3\\]d %\\[4\\]s\n\nUsage:  %\\[5\\]s\n\nRun '%\\[2\\]s --help' for more information","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/required.go","lineNumber":56,"sourceCode":"\t\t}\n\t\treturn fmt.Errorf(\n\t\t\t\"%[1]s: '%[2]s' requires at least %[3]d %[4]s\\n\\nUsage:  %[5]s\\n\\nSee '%[2]s --help' for more information\",\n\t\t\tbinName(cmd),\n\t\t\tcmd.CommandPath(),\n\t\t\tminArgs,\n\t\t\tpluralize(\"argument\", minArgs),\n\t\t\tcmd.UseLine(),\n\t\t)\n\t}\n}\n\n// RequiresMaxArgs returns an error if there is not at most max args\nfunc RequiresMaxArgs(maxArgs int) cobra.PositionalArgs {\n\treturn func(cmd *cobra.Command, args []string) error {\n\t\tif len(args) <= maxArgs {\n\t\t\treturn nil\n\t\t}\n\t\treturn fmt.Errorf(\n\t\t\t\"%[1]s: '%[2]s' requires at most %[3]d %[4]s\\n\\nUsage:  %[5]s\\n\\nRun '%[2]s --help' for more information\",\n\t\t\tbinName(cmd),\n\t\t\tcmd.CommandPath(),\n\t\t\tmaxArgs,\n\t\t\tpluralize(\"argument\", maxArgs),\n\t\t\tcmd.UseLine(),\n\t\t)\n\t}\n}\n\n// RequiresRangeArgs returns an error if there is not at least min args and at most max args\nfunc RequiresRangeArgs(minArgs int, maxArgs int) cobra.PositionalArgs {\n\treturn func(cmd *cobra.Command, args []string) error {\n\t\tif len(args) >= minArgs && len(args) <= maxArgs {\n\t\t\treturn nil\n\t\t}\n\t\treturn fmt.Errorf(\n\t\t\t\"%[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\",","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/required.go#L38-L74","documentation":"Returned by cli.RequiresMaxArgs (required.go:56) when len(args) exceeds the configured maximum. Used by commands that accept a bounded number of positional arguments (e.g. `docker rm NAME...` capped, or commands taking exactly one optional). Message includes the max count and usage.","triggerScenarios":"Invoking a command configured with Args: cli.RequiresMaxArgs(N) with more than N positional arguments, e.g. passing three images to a command that takes one.","commonSituations":"Glob expansion (`*.tar`) producing more files than expected, copy-pasting multiple values where one is allowed, or trailing junk args from a script.","solutions":["Reduce the positional arguments to at most the documented maximum.","If you need to process many items, loop over them calling the command once per item.","Quote/disable uncontrolled glob expansion in your script."],"exampleFix":"// before: too many positionals\ndocker rmi img1 img2 img3   # if command configured RequiresMaxArgs(1)\n\n// after: one per invocation\nfor i in img1 img2 img3; do docker rmi \"$i\"; done","handlingStrategy":"validation","validationCode":"// Cap positionals before invoking\nif len(positionalArgs) > maxArgs {\n    return fmt.Errorf(\"at most %d positional args allowed, got %d\", maxArgs, len(positionalArgs))\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Loop over many items one-at-a-time instead of batching beyond the cap.","Beware unquoted globs expanding to many files.","Validate arg count in wrapper scripts."],"tags":["cli","cobra","usage","arguments"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}