lima-vm/lima · error

unsupported disk format for macOS guest: %s

Error message

unsupported disk format for macOS guest: %s

What it means

The macOS-guest disk creation path only handles the 'asif' and 'raw' formats; if `l.diskImageFormat` holds anything else at disk creation time, the driver returns `unsupported disk format for macOS guest: <format>`. This is a defensive default case since validateConfig normally rejects other formats earlier.

Source

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

	diskSize, err := units.RAMInBytes(*l.Instance.Config.Disk)
	if err != nil {
		return fmt.Errorf("invalid disk size %#q: %w", *l.Instance.Config.Disk, err)
	}

	switch l.diskImageFormat {
	case asif.Type:
		if err := asifutil.NewASIF(disk, diskSize); err != nil {
			return err
		}
	case raw.Type:
		logrus.Debugf("Using %s disk image for macOS guest", l.diskImageFormat)
		diskUtil := &nativeimgutil.NativeImageUtil{}
		if err := diskUtil.CreateDisk(ctx, disk, diskSize); err != nil {
			return fmt.Errorf("failed to create %s disk %#q: %w", l.diskImageFormat, disk, err)
		}
	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)
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Run `limactl start`/`validate` so the config is checked and corrected first
2. Set `vmOpts.vz.diskImageFormat` to 'raw' or 'asif' in the instance's lima.yaml
3. Recreate the instance with a supported format

Example fix

# before
vmOpts:
  vz:
    diskImageFormat: vhd
# after
vmOpts:
  vz:
    diskImageFormat: raw

f := instance.Config.VMOpts["vz"].DiskImageFormat
if f != "" && f != "raw" && f != "asif" {
    // fail fast before CreateDisk
}

func macGuestDiskFormatOK(f string) bool {
    return f == "" || f == "raw" || f == "asif"
}

if err := driver.CreateDisk(ctx); err != nil {
    if strings.Contains(err.Error(), "unsupported disk format") {
        // correct vmOpts.vz.diskImageFormat and retry
    }
}

When it happens

Trigger: `CreateDisk` -> `createDiskMacOSGuest` for a DARWIN guest when the resolved `diskImageFormat` is neither `raw.Type` nor `asif.Type` (e.g. validation was skipped, or the format was set via a code path bypassing validation).

Common situations: Programmatic driver use that constructs an instance without running validateConfig; stale cached config changed between validate and create; future/unknown format strings.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• field `vmOpts.vz.diskImageFormat` must be %#q or %#q, got %#
• `firmware.images` configuration is not supported for VZ driv
• unsupported arch: %#q
• vmOpts.vz.diskImageFormat=%#q requires macOS 26 or higher to
• invalid disk size %#q: %w

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