lima-vm/lima · error

field `vmOpts.vz.diskImageFormat` must be %#q or %#q, got %#

Error message

field `vmOpts.vz.diskImageFormat` must be %#q or %#q, got %#q

What it means

The `vmOpts.vz.diskImageFormat` field only accepts 'raw' or 'asif' for the VZ driver. validateConfig's switch falls through to the default case for any other value and returns this validation error quoting the accepted values and the offending one.

Source

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

	}

	switch videoDisplay := *cfg.Video.Display; videoDisplay {
	case "vz", "default", "none":
	default:
		logrus.Warnf("field `video.display` must be `vz`, `default`, or `none` for VZ driver , got %#q", videoDisplay)
	}
	var vzOpts limatype.VZOpts
	if err := limayaml.Convert(cfg.VMOpts[limatype.VZ], &vzOpts, "vmOpts.vz"); err != nil {
		logrus.WithError(err).Warnf("Couldn't convert %#q", cfg.VMOpts[limatype.VZ])
	}
	switch *vzOpts.DiskImageFormat {
	case raw.Type:
	case asif.Type:
		if macOSProductVersion.LessThan(*semver.New("26.0.0")) {
			return fmt.Errorf("vmOpts.vz.diskImageFormat=%#q requires macOS 26 or higher to run, got %#q", asif.Type, macOSProductVersion)
		}
	default:
		return fmt.Errorf("field `vmOpts.vz.diskImageFormat` must be %#q or %#q, got %#q", raw.Type, asif.Type, *vzOpts.DiskImageFormat)
	}
	return nil
}

func (l *LimaVzDriver) Create(_ context.Context) error {
	identifierFile := filepath.Join(l.Instance.Dir, filenames.VzIdentifier)
	if *l.Instance.Config.OS == limatype.DARWIN {
		_, err := getMacMachineIdentifier(identifierFile)
		return err
	}
	_, err := getGenericMachineIdentifier(identifierFile)
	return err
}

func (l *LimaVzDriver) CreateDisk(ctx context.Context) error {
	if *l.Instance.Config.OS == limatype.DARWIN {
		disk := filepath.Join(l.Instance.Dir, filenames.Disk)
		if !osutil.FileExists(disk) {

View on GitHub (pinned to dd909d0973)

Solutions

1. Change diskImageFormat to 'raw' (the default)
2. Change it to 'asif' if running macOS 26+ and ASIF is desired
3. Remove the `diskImageFormat` key entirely to accept the default

Example fix

# before
vmOpts:
  vz:
    diskImageFormat: qcow2
# after
vmOpts:
  vz:
    diskImageFormat: raw

var vzOpts struct{ DiskImageFormat string `yaml:"diskImageFormat"` }
_ = yaml.Unmarshal(cfg.VMOpts["vz"], &vzOpts)
if f := vzOpts.DiskImageFormat; f != "" && f != "raw" && f != "asif" {
    // fix to "raw" or "asif" before starting
}

func validVZDiskFormat(f string) bool {
    return f == "" || f == "raw" || f == "asif"
}

When it happens

Trigger: Setting `vmOpts.vz.diskImageFormat` to a string other than 'raw' or 'asif' (e.g. 'qcow2', 'raw2', typo values) and starting/validating a VZ instance.

Common situations: Copying diskImageFormat settings from a QEMU template (qcow2 is QEMU-only); typos in the YAML; assuming VZ supports the same formats as QEMU.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unsupported disk format for macOS guest: %s
• `firmware.images` configuration is not supported for VZ driv
• unsupported arch: %#q
• vmOpts.vz.diskImageFormat=%#q requires macOS 26 or higher to
• invalid disk size %#q: %w

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