{"record":{"id":"82134490e0d544b3","repo":"lima-vm/lima","slug":"failed-to-run-wsl-exe-distribution-s-w-out","errorCode":null,"errorMessage":"failed to run `wsl.exe --distribution %s`: %w (out=%#q)","messagePattern":"failed to run `wsl\\.exe --distribution (.+?)`: %w \\(out=%#q\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/wsl2/vm_windows.go","lineNumber":34,"sourceCode":"\t\"strings\"\n\n\t\"github.com/sirupsen/logrus\"\n\n\t\"github.com/lima-vm/lima/v2/pkg/executil\"\n\t\"github.com/lima-vm/lima/v2/pkg/limatype\"\n\t\"github.com/lima-vm/lima/v2/pkg/limatype/filenames\"\n\t\"github.com/lima-vm/lima/v2/pkg/textutil\"\n)\n\n// startVM calls WSL to start a VM.\nfunc startVM(ctx context.Context, distroName string) error {\n\tout, err := executil.RunUTF16leCommand([]string{\n\t\t\"wsl.exe\",\n\t\t\"--distribution\",\n\t\tdistroName,\n\t}, executil.WithContext(ctx))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to run `wsl.exe --distribution %s`: %w (out=%#q)\",\n\t\t\tdistroName, err, out)\n\t}\n\treturn nil\n}\n\n// initVM calls WSL to import a new VM specifically for Lima.\nfunc initVM(ctx context.Context, instanceDir, distroName string) error {\n\tbaseDisk := filepath.Join(instanceDir, filenames.BaseDiskLegacy)\n\tlogrus.Infof(\"Importing distro from %#q to %#q\", baseDisk, instanceDir)\n\tout, err := executil.RunUTF16leCommand([]string{\n\t\t\"wsl.exe\",\n\t\t\"--import\",\n\t\tdistroName,\n\t\tinstanceDir,\n\t\tbaseDisk,\n\t}, executil.WithContext(ctx))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to run `wsl.exe --import %s %s %s`: %w (out=%#q)\",","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/wsl2/vm_windows.go#L16-L52","documentation":"startVM runs `wsl.exe --distribution <distroName>` to boot the Lima-managed WSL distro. If wsl.exe exits non-zero, the driver wraps the error plus the UTF-16LE decoded output in this message. It means WSL itself refused or failed to start the distribution.","triggerScenarios":"Start() -> startVM when wsl.exe returns a non-zero exit: distro not registered, WSL not installed/initialized, distro in a broken state, or WSL service issues.","commonSituations":"The Lima distro was never imported (initVM failed previously); `wsl --shutdown` left the distro stopped in a bad state; WSL2 kernel not installed; Windows features (VirtualMachinePlatform) disabled; low memory causing WSL VM start failure.","solutions":["Run `wsl.exe --list --verbose` to confirm the distro exists and its state; re-import if missing (`limactl delete` + `limactl start` to recreate)","Read the out=... portion of the error — wsl.exe messages are UTF-16 decoded and state the actual reason","Run `wsl.exe --update` and ensure WSL2 (`wsl --set-default-version 2`) is properly installed","Reboot or `wsl.exe --shutdown` then retry if the WSL service is wedged","Check Windows optional features (Virtual Machine Platform, WSL) are enabled"],"exampleFix":"// debugging\n// before: opaque failure\n// after: inspect the embedded output\n// if strings.Contains(out, \"WSL_E_DISTRO_NOT_FOUND\") {\n//     // re-import the distro via limactl delete && limactl start\n// }","handlingStrategy":"try-catch","validationCode":"out, err := exec.Command(\"wsl.exe\", \"--list\", \"--verbose\").Output()\nif err != nil || !strings.Contains(decodeUTF16(out), distroName) {\n    return errors.New(\"distro not registered; run limactl start to import it\")\n}","typeGuard":"func wslDistroExists(name string) bool {\n    out, err := exec.Command(\"wsl.exe\", \"--list\", \"--quiet\").Output()\n    if err != nil { return false }\n    return strings.Contains(decodeUTF16le(string(out)), name)\n}","tryCatchPattern":"if err := driver.Start(ctx); err != nil {\n    var msg string\n    if strings.Contains(err.Error(), \"wsl.exe --distribution\") {\n        msg = extractOutField(err.Error())\n        // branch on WSL error code in msg, e.g. re-import distro\n    }\n    return fmt.Errorf(\"wsl start failed: %s\", msg)\n}","preventionTips":["Verify WSL2 is installed and updated (`wsl --update`, `wsl --set-default-version 2`)","Enable Virtual Machine Platform Windows feature","Don't run `wsl --shutdown` while Lima instances are starting","Keep enough free memory for the WSL VM"],"tags":["wsl2","windows","wsl-exe","vm-start"],"backgroundTag":"wsl-command-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}