lima-vm/lima · error

failed to install macOS: %w

Error message

failed to install macOS: %w

What it means

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.

Source

Thrown at pkg/driver/vz/vz_driver_darwin.go:439

	default:
		return fmt.Errorf("unsupported disk format for macOS guest: %s", l.diskImageFormat)
	}

	if err = ensureIPSW(l.Instance.Dir); err != nil {
		return err
	}
	ipsw := filepath.Join(l.Instance.Dir, filenames.ImageIPSW)

	vm, err := createVMForMacInstaller(ctx, l.Instance)
	if err != nil {
		return err
	}

	logrus.Info("Running macOS installer (takes a few minutes)")
	// FIXME: do we need to run the installer for every new instance,
	// or can we safely reuse the installed disk image?
	if err := installMacOS(ctx, vm, ipsw); err != nil {
		return fmt.Errorf("failed to install macOS: %w", err)
	}

	filesToClean := []string{
		ipsw,
		filepath.Join(l.Instance.Dir, filenames.Image),
	}
	for _, file := range filesToClean {
		if err := os.RemoveAll(file); err != nil {
			logrus.WithError(err).Warnf("Failed to remove %#q", file)
		}
	}

	return nil
}

func (l *LimaVzDriver) Start(ctx context.Context) (chan error, error) {
	logrus.Infof("Starting VZ (hint: to watch the boot progress, see %#q)", filepath.Join(l.Instance.Dir, "serial*.log"))
	vm, waitSSHLocalPortAccessible, errCh, err := startVM(ctx, l.Instance, l.SSHLocalPort, l.onVsockEvent)

View on GitHub (pinned to dd909d0973)

Solutions

1. Delete the instance directory contents (especially image.ipsw, basedisk) and re-run `limactl create` so the IPSW is re-downloaded
2. Inspect the wrapped cause and serial.log for the installer failure detail
3. Update macOS/Lima to pick up Virtualization.framework fixes
4. Retry the create, as the installer can fail transiently

ipsw := filepath.Join(dir, "image.ipsw")
if fi, err := os.Stat(ipsw); err == nil && fi.Size() < expectedMinIPSWSize {
    // delete the truncated IPSW and re-download before installing
    _ = fi
}

if err := driver.CreateDisk(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to install macOS") {
        os.Remove(filepath.Join(dir, "image.ipsw")) // force re-download
        err = driver.CreateDisk(ctx)                 // one retry
    }
}

When it happens

Trigger: `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).

Common situations: 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.

Related errors

• failed to create virtio sound device configuration: %w
• failed to create host audio output stream: %w
• VZ driver requires macOS 13 or higher to run
• `firmware.images` configuration is not supported for VZ driv
• unsupported arch: %#q

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