What causes "cannot use vmType: '%s', error: %w" in abiosoft/colima?

Install Lima with its QEMU dependency: brew install lima (reinstalling colima via brew pulls it automatically)

cannot use vmType: '%s', error: %w

Error message

cannot use vmType: '%s', error: %w

What it means

When vmType is 'qemu', ValidateConfig calls util.AssertQemuImg() to confirm the qemu-img binary is available on the host. If qemu-img is missing or cannot be executed, the failure is wrapped as 'cannot use vmType: qemu'. qemu-img ships with Lima's QEMU dependency and is required to create and manage the VM disk image.

Source

Thrown at config/configmanager/configmanager.go:76

	if _, ok := validMountTypes[c.MountType]; !ok {
		return fmt.Errorf("invalid mountType: '%s'", c.MountType)
	}
	validVMTypes := map[string]bool{"qemu": true}
	if util.MacOS13OrNewer() {
		validVMTypes["vz"] = true
	}
	if util.MacOS13OrNewerOnArm() {
		validVMTypes["krunkit"] = true
	}
	if c.VMType == "krunkit" && !util.MacOS13OrNewerOnArm() {
		return fmt.Errorf("vmType 'krunkit' is only available on macOS with Apple Silicon")
	}
	if _, ok := validVMTypes[c.VMType]; !ok {
		return fmt.Errorf("invalid vmType: '%s'", c.VMType)
	}
	if c.VMType == "qemu" {
		if err := util.AssertQemuImg(); err != nil {
			return fmt.Errorf("cannot use vmType: '%s', error: %w", c.VMType, err)
		}
	}
	if c.VMType == "krunkit" {
		if err := util.AssertKrunkit(); err != nil {
			return fmt.Errorf("cannot use vmType: '%s', error: %w", c.VMType, err)
		}
	}

	if c.DiskImage != "" {
		if strings.HasPrefix(c.DiskImage, "http://") || strings.HasPrefix(c.DiskImage, "https://") {
			return fmt.Errorf("cannot use diskImage: remote URLs not supported, only local files can be specified")
		}
	}

	if _, ok := validPortForwarders[c.PortForwarder]; !ok {
		return fmt.Errorf("invalid port forwarder: '%s'", c.PortForwarder)
	}

View on GitHub (pinned to c3a5f9184d)

Solutions

Install Lima with its QEMU dependency: brew install lima (reinstalling colima via brew pulls it automatically)
Verify the binary: qemu-img --version; if it exists but is not found, fix PATH to include the brew bin directory
As a workaround on macOS 13+, switch vmType to 'vz' which does not require qemu-img

Example fix

# before
qemu-img: command not found
colima start   # cannot use vmType: 'qemu'

# after
brew install lima && qemu-img --version && colima start

Defensive patterns

Strategy: validation

Validate before calling

if c.VMType == "qemu" {
    if _, err := exec.LookPath("qemu-img"); err != nil {
        // install lima (brew install lima) or fix PATH before starting
    }
}

Try / catch

if err := configmanager.ValidateConfig(c); err != nil {
    if strings.Contains(err.Error(), "cannot use vmType") && c.VMType == "qemu" {
        // qemu-img missing: install lima or switch to 'vz' on macOS 13+
    }
}

Prevention

Install colima via brew so lima and qemu-img are pulled in together
Verify 'qemu-img --version' works in the exact shell or service context that runs colima
Include the brew bin dir in PATH for launchd/systemd/CI environments

When it happens

Trigger: vmType: qemu while exec.LookPath-style checks for qemu-img fail: Lima not installed (source-built colima without brew), a custom lima without QEMU tooling, or a PATH missing the brew prefix in GUI-launched or service contexts.

Common situations: Installing colima from source without 'brew install lima'; running from an IDE terminal or launchd where /opt/homebrew/bin is not in PATH; a brew upgrade that unlinked or removed qemu artifacts.

Related errors

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/66d3f6d0ff1c3e33. Report an issue: GitHub.