What causes "must have two image references" in slimtoolkit/slim?

Pass two image references: `slim merge --image image1 --image image2`.

must have two image references

Error message

must have two image references

What it means

The merge command combines two container images into one. When the --image flag is used, CommandFlagValues requires exactly two values; fewer than two fails with 'must have two image references'. The error is printed as a param.image output and command help is shown.

Source

Thrown at pkg/app/master/command/merge/cli.go:75

type CommandParams struct {
	FirstImage           string   `json:"first_image"`
	LastImage            string   `json:"last_image"`
	UseLastImageMetadata bool     `json:"use_last_image_metadata"`
	OutputTags           []string `json:"output_tags"`
}

func CommandFlagValues(xc *app.ExecutionContext, ctx *cli.Context) (*CommandParams, error) {
	values := &CommandParams{
		UseLastImageMetadata: ctx.Bool(FlagUseLastImageMetadata),
		OutputTags:           ctx.StringSlice(FlagTag),
	}

	images := ctx.StringSlice(FlagImage)
	if len(images) > 0 {
		if len(images) < 2 {
			xc.Out.Error("param.image", "must have two image references")
			cli.ShowCommandHelp(ctx, Name)
			return nil, fmt.Errorf("must have two image references")
		}

		values.FirstImage = images[0]
		values.LastImage = images[1]
	}

	if ctx.Args().Len() > 0 {
		if ctx.Args().Len() < 2 {
			xc.Out.Error("param.image", "must have two image references")
			cli.ShowCommandHelp(ctx, Name)
			return nil, fmt.Errorf("must have two image references")
		}

		values.FirstImage = ctx.Args().Get(0)
		values.LastImage = ctx.Args().Get(1)
	}

	if values.FirstImage == "" || values.LastImage == "" {

View on GitHub (pinned to 81940d17fa)

Solutions

Pass two image references: `slim merge --image image1 --image image2`.
Or pass them as positional arguments: `slim merge image1 image2`.
Quote image references containing tags/digests so the shell doesn't split them.
Check the printed command help (shown automatically) for the expected flag usage.

Example fix

// before
slim merge --image myrepo/app:1.0
// after
slim merge --image myrepo/app:1.0 --image myrepo/app:2.0

Defensive patterns

Strategy: validation

Validate before calling

images=()
while IFS= read -r x; do images+=("$x"); done < <(parse_flags)  # collect --image values
[ "${#images[@]}" -eq 2 ] || { echo "merge needs exactly 2 images"; exit 2; }

Try / catch

if err := runMerge(args); err != nil && strings.Contains(err.Error(), "must have two image references") {
    // print usage and exit with input-validation code
}

Prevention

Always pass --image exactly twice (or two positional args)
Quote image refs with tags/digests
Validate arg counts in CI wrapper scripts before invoking slim

When it happens

Trigger: Running `slim merge --image <one-image>` (a single --image value, or a repeated flag count < 2) before flag parsing completes in merge/cli.go CommandFlagValues.

Common situations: Providing only one --image flag; quoting mistakes causing the second image to be swallowed into one argument; forgetting that positional args and --image flags are separate mechanisms; shell glob not expanding.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of slimtoolkit/slim@81940d17fa (2026-08-31). Data as JSON: /api/errors/484b581bc41ca8e0. Report an issue: GitHub.