wagoodman/dive · error

exactly one argument is required

Error message

exactly one argument is required

What it means

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.

Source

Thrown at cmd/dive/cli/internal/command/root.go:36

type rootOptions struct {
	options.Application `yaml:",inline" mapstructure:",squash"`

	// reserved for future use of root-only flags
}

func Root(app clio.Application) *cobra.Command {
	opts := &rootOptions{
		Application: options.DefaultApplication(),
	}
	return app.SetupRootCommand(&cobra.Command{
		Use:   "dive [IMAGE]",
		Short: "Docker Image Visualizer & Explorer",
		Long: `This tool provides a way to discover and explore the contents of a docker image. Additionally the tool estimates
the amount of wasted space and identifies the offending files from the image.`,
		Args: func(cmd *cobra.Command, args []string) error {
			if len(args) != 1 {
				return fmt.Errorf("exactly one argument is required")
			}
			opts.Analysis.Image = args[0]
			return nil
		},
		RunE: func(cmd *cobra.Command, _ []string) error {
			if err := setUI(app, opts.Application); err != nil {
				return fmt.Errorf("failed to set UI: %w", err)
			}

			resolver, err := dive.GetImageResolver(opts.Analysis.Source)
			if err != nil {
				return fmt.Errorf("cannot determine image provider to fetch from: %w", err)
			}

			ctx := cmd.Context()

			img, err := adapter.ImageResolver(resolver).Fetch(ctx, opts.Analysis.Image)
			if err != nil {

View on GitHub (pinned to d6c691947f)

Solutions

1. Pass exactly one image reference: dive nginx:1.27
2. Quote variables and default them in CI: dive "${IMAGE:?image not set}"
3. Loop over multiple images instead of passing them together: for img in a b; do dive "$img"; done
4. Check for accidental leading flags that DisableFlagParsing does not consume on the root command

Example fix

# before
dive $IMAGE $TAG   # splits into two args when TAG is set

# after
dive "${IMAGE}:${TAG:-latest}"

# shell: require exactly one non-empty image reference
[ $# -eq 1 ] && [ -n "$1" ] || { echo 'usage: dive <image>'; exit 2; }
dive "$1"

func isValidImageRefArg(args []string) bool {
    return len(args) == 1 && args[0] != ""
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• cannot export analysis: %w
• unable to determine image source from %q: %v
• failed to unmarshal CI config file %s: %w
• directory for JSON export does not exist: %s
• file tree has path errors (use '--ignore-errors' to attempt

AI-assisted analysis of wagoodman/dive@d6c691947f (2026-08-15). Data as JSON: /api/errors/76a6414fe6736bba. Report an issue: GitHub.