currently Windows guest OS is only supported on QEMU

Error message

currently Windows guest OS is only supported on QEMU

What it means

The WSL2 driver rejects Lima configs whose guest OS is set to Windows. The WSL2 backend only knows how to boot Linux distributions inside WSL, so any config with os: windows fails config validation before any VM is created. It is thrown by validateConfig, which runs during driver Configure/Validate.

Source

Thrown at pkg/driver/wsl2/wsl_driver_windows.go:112

	return validateConfig(ctx, l.Instance.Config)
}

func validateConfig(_ context.Context, cfg *limatype.LimaYAML) error {
	if cfg == nil {
		return errors.New("configuration is nil")
	}
	if cfg.MountType != nil && *cfg.MountType != limatype.WSLMount {
		return fmt.Errorf("field `mountType` must be %#q for WSL2 driver, got %#q", limatype.WSLMount, *cfg.MountType)
	}
	// TODO: revise this list for WSL2
	if cfg.VMType != nil {
		if unknown := reflectutil.UnknownNonEmptyFields(cfg, knownYamlProperties...); len(unknown) > 0 {
			logrus.Warnf("Ignoring: vmType %s: %+v", *cfg.VMType, unknown)
		}
	}

	if cfg.OS != nil && *cfg.OS == limatype.WINDOWS {
		return errors.New("currently Windows guest OS is only supported on QEMU")
	}

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

	if cfg.TPM != nil && *cfg.TPM {
		return errors.New("field `tpm` is not supported on WSL2 driver")
	}

	if cfg.VMType != nil {
		if cfg.Images != nil && cfg.Arch != nil {
			// TODO: real filetype checks
			tarFileRegex := regexp.MustCompile(`\.(tar|tgz|txz|tbz2|tzst|tar\.(gz|xz|bz2|zstd|zst))$`)
			unsupportedVMImgRegex := regexp.MustCompile(`\.(qcow2|raw|img|iso|ipsw)(\.(gz|xz|bz2|zstd|zst))?$`)
			squashfsRegex := regexp.MustCompile(`\.squashfs(\.(gz|xz|bz2|zstd|zst))?$`)
			for i, image := range cfg.Images {
				if unknown := reflectutil.UnknownNonEmptyFields(image, "File", "Variant", "ArchVariant"); len(unknown) > 0 {

View on GitHub (pinned to dd909d0973)

Solutions

Remove the `os: windows` line from lima.yaml (Linux is the only supported guest on wsl2)
Change vmType to qemu if a Windows guest is genuinely required
Verify with `limactl validate <file>` before creating the instance

Example fix

# before
os: windows
vmType: wsl2
# after
# remove 'os: windows' (Linux guest implied), or:
os: linux
vmType: wsl2

Defensive patterns

Strategy: validation

Validate before calling

import "github.com/lima-vm/lima/v2/pkg/limatype"
func validGuestOSForWSL2(cfg *limatype.LimaYAML) bool {
	return cfg.OS == nil || *cfg.OS != limatype.WINDOWS
}
// call before Configure/start when vmType == "wsl2"

Type guard

func isWindowsGuest(cfg *limatype.LimaYAML) bool {
	return cfg.OS != nil && *cfg.OS == limatype.WINDOWS
}
// if isWindowsGuest(cfg) { use qemu driver instead }

Try / catch

if err := driver.Configure(ctx, cfg); err != nil {
	if strings.Contains(err.Error(), "Windows guest OS is only supported on QEMU") {
		// fall back to qemu driver or strip os field
	}
	return err
}

Prevention

Never set os: windows in templates intended for wsl2
Run `limactl validate <yaml>` before create/start
Keep separate template sets for wsl2 and qemu drivers

When it happens

Trigger: Creating or starting an instance on Windows where lima.yaml contains `os: windows` (i.e. cfg.OS == limatype.WINDOWS) while vmType is wsl2. Any call path through Configure, Validate, or limactl create/start that loads such a config hits this.

Common situations: Users copying QEMU-oriented examples that set os: windows to run Windows guests, or editing templates for Windows guest testing, while their default vmType is wsl2.

Related errors

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