{"record":{"id":"d589c88ba84b60b5","repo":"lima-vm/lima","slug":"failed-to-install-macos-w","errorCode":null,"errorMessage":"failed to install macOS: %w","messagePattern":"failed to install macOS: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/vz/vz_driver_darwin.go","lineNumber":439,"sourceCode":"\tdefault:\n\t\treturn fmt.Errorf(\"unsupported disk format for macOS guest: %s\", l.diskImageFormat)\n\t}\n\n\tif err = ensureIPSW(l.Instance.Dir); err != nil {\n\t\treturn err\n\t}\n\tipsw := filepath.Join(l.Instance.Dir, filenames.ImageIPSW)\n\n\tvm, err := createVMForMacInstaller(ctx, l.Instance)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tlogrus.Info(\"Running macOS installer (takes a few minutes)\")\n\t// FIXME: do we need to run the installer for every new instance,\n\t// or can we safely reuse the installed disk image?\n\tif err := installMacOS(ctx, vm, ipsw); err != nil {\n\t\treturn fmt.Errorf(\"failed to install macOS: %w\", err)\n\t}\n\n\tfilesToClean := []string{\n\t\tipsw,\n\t\tfilepath.Join(l.Instance.Dir, filenames.Image),\n\t}\n\tfor _, file := range filesToClean {\n\t\tif err := os.RemoveAll(file); err != nil {\n\t\t\tlogrus.WithError(err).Warnf(\"Failed to remove %#q\", file)\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc (l *LimaVzDriver) Start(ctx context.Context) (chan error, error) {\n\tlogrus.Infof(\"Starting VZ (hint: to watch the boot progress, see %#q)\", filepath.Join(l.Instance.Dir, \"serial*.log\"))\n\tvm, waitSSHLocalPortAccessible, errCh, err := startVM(ctx, l.Instance, l.SSHLocalPort, l.onVsockEvent)","sourceCodeStart":421,"sourceCodeEnd":457,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/vz/vz_driver_darwin.go#L421-L457","documentation":"After creating the disk and booting a temporary VM, the VZ driver runs the macOS installer against the downloaded IPSW via `installMacOS`. If the installer fails, the error is wrapped as `failed to install macOS: <cause>`. The code even carries a FIXME noting the installer currently runs for every new instance.","triggerScenarios":"`CreateDisk` -> `createDiskMacOSGuest` where the `vz.VirtualizationFrameworkInstaller`-style VM boots but `installMacOS(ctx, vm, ipsw)` returns an error (installer crash, timeout, corrupted IPSW, Virtualization.framework error).","commonSituations":"Interrupted/corrupted `image.ipsw` download; macOS version mismatch between the IPSW and the host; Virtualization.framework installer bugs; host under heavy load causing installer timeouts.","solutions":["Delete the instance directory contents (especially image.ipsw, basedisk) and re-run `limactl create` so the IPSW is re-downloaded","Inspect the wrapped cause and serial.log for the installer failure detail","Update macOS/Lima to pick up Virtualization.framework fixes","Retry the create, as the installer can fail transiently"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"ipsw := filepath.Join(dir, \"image.ipsw\")\nif fi, err := os.Stat(ipsw); err == nil && fi.Size() < expectedMinIPSWSize {\n    // delete the truncated IPSW and re-download before installing\n    _ = fi\n}","typeGuard":null,"tryCatchPattern":"if err := driver.CreateDisk(ctx); err != nil {\n    if strings.Contains(err.Error(), \"failed to install macOS\") {\n        os.Remove(filepath.Join(dir, \"image.ipsw\")) // force re-download\n        err = driver.CreateDisk(ctx)                 // one retry\n    }\n}","preventionTips":["Ensure stable network for the IPSW download","Keep macOS and Lima up to date for Virtualization.framework fixes","Check serial*.log in the instance dir when the installer fails","Avoid interrupting `limactl create` mid-install"],"tags":["macos","vz","installer","virtualization-framework"],"backgroundTag":"guest-install-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}