{"record":{"id":"983a5fb9163a7bdc","repo":"lima-vm/lima","slug":"currently-windows-guest-os-is-only-supported-on-qe-983a5f","errorCode":null,"errorMessage":"currently Windows guest OS is only supported on QEMU","messagePattern":"currently Windows guest OS is only supported on QEMU","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/wsl2/wsl_driver_windows.go","lineNumber":112,"sourceCode":"\treturn validateConfig(ctx, l.Instance.Config)\n}\n\nfunc validateConfig(_ context.Context, cfg *limatype.LimaYAML) error {\n\tif cfg == nil {\n\t\treturn errors.New(\"configuration is nil\")\n\t}\n\tif cfg.MountType != nil && *cfg.MountType != limatype.WSLMount {\n\t\treturn fmt.Errorf(\"field `mountType` must be %#q for WSL2 driver, got %#q\", limatype.WSLMount, *cfg.MountType)\n\t}\n\t// TODO: revise this list for WSL2\n\tif cfg.VMType != nil {\n\t\tif unknown := reflectutil.UnknownNonEmptyFields(cfg, knownYamlProperties...); len(unknown) > 0 {\n\t\t\tlogrus.Warnf(\"Ignoring: vmType %s: %+v\", *cfg.VMType, unknown)\n\t\t}\n\t}\n\n\tif cfg.OS != nil && *cfg.OS == limatype.WINDOWS {\n\t\treturn errors.New(\"currently Windows guest OS is only supported on QEMU\")\n\t}\n\n\tif !limatype.IsNativeArch(*cfg.Arch) {\n\t\treturn fmt.Errorf(\"unsupported arch: %#q\", *cfg.Arch)\n\t}\n\n\tif cfg.TPM != nil && *cfg.TPM {\n\t\treturn errors.New(\"field `tpm` is not supported on WSL2 driver\")\n\t}\n\n\tif cfg.VMType != nil {\n\t\tif cfg.Images != nil && cfg.Arch != nil {\n\t\t\t// TODO: real filetype checks\n\t\t\ttarFileRegex := regexp.MustCompile(`\\.(tar|tgz|txz|tbz2|tzst|tar\\.(gz|xz|bz2|zstd|zst))$`)\n\t\t\tunsupportedVMImgRegex := regexp.MustCompile(`\\.(qcow2|raw|img|iso|ipsw)(\\.(gz|xz|bz2|zstd|zst))?$`)\n\t\t\tsquashfsRegex := regexp.MustCompile(`\\.squashfs(\\.(gz|xz|bz2|zstd|zst))?$`)\n\t\t\tfor i, image := range cfg.Images {\n\t\t\t\tif unknown := reflectutil.UnknownNonEmptyFields(image, \"File\", \"Variant\", \"ArchVariant\"); len(unknown) > 0 {","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/wsl2/wsl_driver_windows.go#L94-L130","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nos: windows\nvmType: wsl2\n# after\n# remove 'os: windows' (Linux guest implied), or:\nos: linux\nvmType: wsl2","handlingStrategy":"validation","validationCode":"import \"github.com/lima-vm/lima/v2/pkg/limatype\"\nfunc validGuestOSForWSL2(cfg *limatype.LimaYAML) bool {\n\treturn cfg.OS == nil || *cfg.OS != limatype.WINDOWS\n}\n// call before Configure/start when vmType == \"wsl2\"","typeGuard":"func isWindowsGuest(cfg *limatype.LimaYAML) bool {\n\treturn cfg.OS != nil && *cfg.OS == limatype.WINDOWS\n}\n// if isWindowsGuest(cfg) { use qemu driver instead }","tryCatchPattern":"if err := driver.Configure(ctx, cfg); err != nil {\n\tif strings.Contains(err.Error(), \"Windows guest OS is only supported on QEMU\") {\n\t\t// fall back to qemu driver or strip os field\n\t}\n\treturn err\n}","preventionTips":["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"],"tags":["wsl2","config-validation","windows-guest"],"backgroundTag":"unsupported-guest-os","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}