lima-vm/lima · error

currently Windows guest is only supported on [%#q, %#q]; got

Error message

currently Windows guest is only supported on [%#q, %#q]; got %#q

What it means

Lima validates the `os` field of a lima.yaml template against the set of supported guest operating systems. When `os: windows` is selected, Windows guests are currently only supported by the QEMU driver and only on x86_64 or aarch64 architectures; any other VM type triggers this error. It is thrown during Validate(), which runs on every create, edit, restart, and template validation action.

Source

Thrown at pkg/limayaml/validate.go:58

	if y.MinimumLimaVersion != nil {
		if _, err := versionutil.Parse(*y.MinimumLimaVersion); err != nil {
			errs = errors.Join(errs, fmt.Errorf("field `minimumLimaVersion` must be a semvar value, got %#q: %w", *y.MinimumLimaVersion, err))
		}
		// Unparsable version.Version (like commit hashes or "<unknown>") is treated as "latest/greatest"
		// and will pass all version comparisons, allowing development builds to work.
		if !versionutil.GreaterEqual(version.Version, *y.MinimumLimaVersion) {
			errs = errors.Join(errs, fmt.Errorf("template requires Lima version %#q; this is only %#q", *y.MinimumLimaVersion, version.Version))
		}
	}

	switch *y.OS {
	case limatype.LINUX, limatype.DARWIN, limatype.FREEBSD:
	case limatype.WINDOWS:
		if *y.VMType != limatype.QEMU {
			errs = errors.Join(errs, fmt.Errorf("currently Windows guest is only supported on %#q; got %#q", limatype.QEMU, *y.VMType))
		}
		if !slices.Contains([]limatype.Arch{limatype.X8664, limatype.AARCH64}, *y.Arch) {
			errs = errors.Join(errs, fmt.Errorf("currently Windows guest is only supported on [%#q, %#q]; got %#q", limatype.X8664, limatype.AARCH64, *y.Arch))
		}
	default:
		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))
		}
	}

View on GitHub (pinned to dd909d0973)

Solutions

  1. Change `vmType` to `qemu` in the template
  2. Remove the `os: windows` override to use the default Linux guest with the preferred driver
  3. Use a template designed for Windows guests under QEMU

Example fix

// before
os: windows
vmType: vz
// after
os: windows
vmType: qemu
Defensive patterns

Strategy: validation

Validate before calling

func validWindowsVMType(os, vmType, arch string) bool {
	if os != "windows" {
		return true
	}
	return vmType == "qemu" && (arch == "x86_64" || arch == "aarch64")
}

Type guard

func isWindowsCompatible(y *limatype.LimaYAML) bool {
	return *y.OS != limatype.WINDOWS || *y.VMType == limatype.QEMU
}

Try / catch

if err := limayaml.Validate(y, false); err != nil {
	if strings.Contains(err.Error(), "Windows guest is only supported") {
		// fix vmType to qemu before proceeding
	}
	return err
}

Prevention

When it happens

Trigger: A template sets `os: windows` while `vmType` is something other than "qemu" (e.g. vz, vz-rosa, wsl2), and Validate() is invoked via limactl create/edit/restart/start or template validation.

Common situations: Users copy a vz-based macOS template and change os to windows; users on Apple Silicon try vz with a Windows guest; templates hand-edited for experimentation.

Related errors

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