lima-vm/lima · error

`firmware.images` configuration is not supported for VZ…

Error message

`firmware.images` configuration is not supported for VZ driver

What it means

Lima's VZ driver cannot boot custom firmware images; Virtualization.framework only supports booting via a macOS IPSW or a Linux kernel/initrd, not legacy BIOS/UEFI ROM images. During config validation, if any entry in `firmware.images` matches the current VM type (empty string or 'vz') and targets the host's architecture, validation fails immediately. This catches the config early instead of failing obscurely at VM start.

Solutions

1. Remove the `firmware.images` entries from the configuration
2. Scope the firmware entry to another driver by setting its `vmType: qemu` (or an arch different from the guest arch) so VZ ignores it
3. Use vmType 'qemu' if custom firmware is genuinely required

Example fix

# before
firmware:
  images:
    - location: ~/Downloads/OVMF.fd
      arch: aarch64
# after
firmware:
  images:
    - location: ~/Downloads/OVMF.fd
      arch: aarch64
      vmType: qemu

import "golang.org/x/exp/yaml" // parse lima.yaml first
var cfg LimaYAML
_ = yaml.Unmarshal(data, &cfg)
for _, f := range cfg.Firmware.Images {
    if (f.VMType == "" || f.VMType == "vz") && f.Arch == runtime.GOARCH {
        // drop the entry or set vmType: qemu before starting
    }
}

func firmwareForbiddenForVZ(f FirmwareImage, arch string) bool {
    return (f.VMType == "" || f.VMType == "vz") && f.Arch == arch
}

When it happens

Trigger: Running `limactl start`/`validate` with vmType 'vz' while the YAML contains `firmware.images:` entries whose `vmType` is omitted or set to 'vz' and whose `arch` equals the configured guest arch (which defaults to the native arch).

Common situations: Copying a QEMU-oriented template that sets custom UEFI/BIOS firmware into a VZ instance; adding firmware images for aarch64/x86_64 cross-arch leftovers that happen to match the native arch; merging templates that include a `firmware:` section.

Related errors

• field `vmOpts.vz.diskImageFormat` must be %#q or %#q, got…
• invalid disk size %#q
• RunGUI is not supported for the given driver
• unsupported arch: %#q
• unsupported disk format for macOS guest

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/0ad6743788c456fb. Report an issue: GitHub.

Appendix: source

Thrown at pkg/driver/vz/vz_driver_darwin.go:292

			*cfg.VMType)
	}
	if cfg.MountType != nil && *cfg.MountType == limatype.NINEP {
		return fmt.Errorf("field `mountType` must be %#q or %#q for VZ driver , got %#q", limatype.REVSSHFS, limatype.VIRTIOFS, *cfg.MountType)
	}
	if cfg.TPM != nil && *cfg.TPM {
		return errors.New("field `tpm` is not supported on VZ driver")
	}
	if cfg.OS != nil && *cfg.OS == limatype.WINDOWS {
		return errors.New("currently Windows guest OS is only supported on QEMU")
	}
	if *cfg.Firmware.LegacyBIOS {
		logrus.Warnf("vmType %s: ignoring `firmware.legacyBIOS`", *cfg.VMType)
	}
	for _, f := range cfg.Firmware.Images {
		switch f.VMType {
		case "", limatype.VZ:
			if f.Arch == *cfg.Arch {
				return errors.New("`firmware.images` configuration is not supported for VZ driver")
			}
		}
	}
	if unknown := reflectutil.UnknownNonEmptyFields(cfg, knownYamlProperties...); cfg.VMType != nil && len(unknown) > 0 {
		logrus.Warnf("vmType %s: ignoring %+v", *cfg.VMType, unknown)
	}

	if !limatype.IsNativeArch(*cfg.Arch) {
		return fmt.Errorf("unsupported arch: %#q", *cfg.Arch)
	}

	for i, image := range cfg.Images {
		if unknown := reflectutil.UnknownNonEmptyFields(image, "File", "Kernel", "Initrd", "Variant", "ArchVariant"); len(unknown) > 0 {
			logrus.Warnf("vmType %s: ignoring images[%d]: %+v", *cfg.VMType, i, unknown)
		}
	}

	for i, mount := range cfg.Mounts {

View on GitHub (pinned to dd909d0973)