{"record":{"id":"76a6414fe6736bba","repo":"wagoodman/dive","slug":"exactly-one-argument-is-required","errorCode":null,"errorMessage":"exactly one argument is required","messagePattern":"exactly one argument is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/dive/cli/internal/command/root.go","lineNumber":36,"sourceCode":"\ntype rootOptions struct {\n\toptions.Application `yaml:\",inline\" mapstructure:\",squash\"`\n\n\t// reserved for future use of root-only flags\n}\n\nfunc Root(app clio.Application) *cobra.Command {\n\topts := &rootOptions{\n\t\tApplication: options.DefaultApplication(),\n\t}\n\treturn app.SetupRootCommand(&cobra.Command{\n\t\tUse:   \"dive [IMAGE]\",\n\t\tShort: \"Docker Image Visualizer & Explorer\",\n\t\tLong: `This tool provides a way to discover and explore the contents of a docker image. Additionally the tool estimates\nthe amount of wasted space and identifies the offending files from the image.`,\n\t\tArgs: func(cmd *cobra.Command, args []string) error {\n\t\t\tif len(args) != 1 {\n\t\t\t\treturn fmt.Errorf(\"exactly one argument is required\")\n\t\t\t}\n\t\t\topts.Analysis.Image = args[0]\n\t\t\treturn nil\n\t\t},\n\t\tRunE: func(cmd *cobra.Command, _ []string) error {\n\t\t\tif err := setUI(app, opts.Application); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to set UI: %w\", err)\n\t\t\t}\n\n\t\t\tresolver, err := dive.GetImageResolver(opts.Analysis.Source)\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"cannot determine image provider to fetch from: %w\", err)\n\t\t\t}\n\n\t\t\tctx := cmd.Context()\n\n\t\t\timg, err := adapter.ImageResolver(resolver).Fetch(ctx, opts.Analysis.Image)\n\t\t\tif err != nil {","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/wagoodman/dive/blob/d6c691947f8fda635c952a17ee3b7555379d58f0/cmd/dive/cli/internal/command/root.go#L18-L54","documentation":"Returned by the root command's Args validator when `dive` is invoked without exactly one positional argument (the image reference). Cobra runs this before RunE, so no engine or network activity happens first; extra arguments are equally rejected because image references cannot contain spaces unquoted.","triggerScenarios":"Running bare `dive`; `dive img1 img2`; quoting mistakes that split one reference into two args (unquoted trailing tag); or wrapping scripts that forward variable args where the variable is empty.","commonSituations":"CI variables that are empty on some branches (dive $IMAGE with IMAGE unset); copy-pasting a command with a stale extra flag parsed as a positional; shell loops passing multiple images to a command that accepts one.","solutions":["Pass exactly one image reference: dive nginx:1.27","Quote variables and default them in CI: dive \"${IMAGE:?image not set}\"","Loop over multiple images instead of passing them together: for img in a b; do dive \"$img\"; done","Check for accidental leading flags that DisableFlagParsing does not consume on the root command"],"exampleFix":"# before\ndive $IMAGE $TAG   # splits into two args when TAG is set\n\n# after\ndive \"${IMAGE}:${TAG:-latest}\"","handlingStrategy":"validation","validationCode":"# shell: require exactly one non-empty image reference\n[ $# -eq 1 ] && [ -n \"$1\" ] || { echo 'usage: dive <image>'; exit 2; }\ndive \"$1\"","typeGuard":"func isValidImageRefArg(args []string) bool {\n    return len(args) == 1 && args[0] != \"\"\n}","tryCatchPattern":null,"preventionTips":["Quote image references in scripts and CI variables","Fail fast on empty image variables: \"${IMAGE:?unset}\"","Loop over images one at a time instead of passing several"],"tags":["cli","arguments","usage","cobra"],"backgroundTag":null,"analyzedSha":"d6c691947f8fda635c952a17ee3b7555379d58f0","analyzedAt":"2026-08-15T09:42:35.293Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}