lima-vm/lima · critical

field `images` must be set

Error message

field `images` must be set

What it means

The `images` field is empty after defaults are applied, so there is no disk image to boot the instance from.

Source

Thrown at pkg/limayaml/validate.go:79

		errs = errors.Join(errs, fmt.Errorf("field `os` must be one of %#q; got %#q", limatype.OSTypes, *y.OS))
	}
	if !slices.Contains(limatype.ArchTypes, *y.Arch) {
		errs = errors.Join(errs, fmt.Errorf("field `arch` must be one of %v; got %#q", limatype.ArchTypes, *y.Arch))
	}

	if y.User.Shell != nil {
		shell := *y.User.Shell
		if *y.OS == limatype.WINDOWS {
			if !IsSupportedWindowsShell(shell) {
				errs = errors.Join(errs, fmt.Errorf("field `user.shell` must be one of %v for Windows guest, got %#q", SupportedWindowsShells, shell))
			}
		} else if !path.IsAbs(shell) {
			errs = errors.Join(errs, fmt.Errorf("field `user.shell` must be an absolute path, got %#q", shell))
		}
	}

	if len(y.Images) == 0 {
		errs = errors.Join(errs, errors.New("field `images` must be set"))
	}
	for i, f := range y.Images {
		err := validateFileObject(f.File, fmt.Sprintf("images[%d]", i))
		if err != nil {
			errs = errors.Join(errs, err)
		}
		if f.Kernel != nil {
			err := validateFileObject(f.Kernel.File, fmt.Sprintf("images[%d].kernel", i))
			if err != nil {
				errs = errors.Join(errs, err)
			}
			if f.Kernel.Arch != f.Arch {
				errs = errors.Join(errs, fmt.Errorf("images[%d].kernel has unexpected architecture %#q, must be %#q", i, f.Kernel.Arch, f.Arch))
			}
		}
		if f.Initrd != nil {
			err := validateFileObject(*f.Initrd, fmt.Sprintf("images[%d].initrd", i))
			if err != nil {

View on GitHub (pinned to dd909d0973)

Solutions

  1. Add an `images` entry with a valid `location` (ISO or disk image URL/path) and matching `arch`
  2. Start from an existing template (e.g. templates/default.yaml) that includes images
  3. Ensure image entries' arch matches the instance `arch` so at least one applies

Example fix

// before
images: []
// after
images:
- location: https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img
  arch: x86_64
Defensive patterns

Strategy: validation

Validate before calling

func hasBootableImage(y *limatype.LimaYAML, arch string) bool {
	for _, img := range y.Images {
		if string(img.Arch) == arch {
			return true
		}
	}
	return false
}

Type guard

func hasImages(y *limatype.LimaYAML) bool {
	return y != nil && len(y.Images) > 0
}

Try / catch

if err := limayaml.Validate(y, false); err != nil {
	if strings.Contains(err.Error(), "field `images` must be set") {
		return fmt.Errorf("template has no bootable image: %w", err)
	}
	return err
}

Prevention

When it happens

Trigger: Template with no `images:` entries, images stripped during editing, or images conditional on an arch/OS that filtered out every entry for the current host.

Common situations: Minimal hand-written templates missing images; copying only the non-images part of a template; arch-specific image list not matching the chosen `arch`.

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 lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/145589d81e21b788. Report an issue: GitHub.