abiosoft/colima · error

qemu is required to emulate %s: %w

Error message

qemu is required to emulate %s: %w

What it means

Returned by assertQemu when qemu-img is not installed on the host AND the VM type is QEMU AND the guest architecture differs from the host architecture. Cross-architecture QEMU VMs need the qemu binaries to emulate the guest CPU, so colima aborts startup with this wrapped error naming the target architecture.

Source

Thrown at environment/vm/lima/lima.go:382

		// if additional disk is present, then it must've been formatted correctly.
		if err := store.Set(func(s *store.Store) {
			s.DiskFormatted = true
		}); err != nil {
			// not fatal, but should be logged
			logrus.Warnln(fmt.Errorf("error persisting store settings: %w", err))
		}

		return nil
	})

}

func (l *limaVM) assertQemu() error {
	// assert qemu requirement
	sameArchitecture := environment.HostArch() == l.limaConf.Arch
	if err := util.AssertQemuImg(); err != nil && l.limaConf.VMType == limaconfig.QEMU {
		if !sameArchitecture {
			return fmt.Errorf("qemu is required to emulate %s: %w", l.limaConf.Arch, err)
		}
		return err
	}
	return nil
}

const envLimaSSHPortForwarder = "LIMA_SSH_PORT_FORWARDER"

func (l *limaVM) prepareHost(conf config.Config) {
	useSSHPortForwarder := conf.PortForwarder != "grpc"

	l.host = l.host.WithEnv(envLimaSSHPortForwarder + "=" + strconv.FormatBool(useSSHPortForwarder))
}

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Install qemu: 'brew install qemu' (macOS) or 'apt-get install qemu-system' / 'dnf install qemu-system-*' (Linux)
2. On Apple Silicon prefer virtualization: 'colima start --vz-rosetta --vz' which runs amd64 containers via Rosetta without full emulation
3. If you do not need another architecture, drop --arch so it matches the host
4. Verify with 'qemu-img --version' that PATH resolution works in the shell/launchd context

Example fix

# before
colima start --arch x86_64   # fails: qemu is required to emulate x86_64
# after (Apple Silicon, no qemu needed)
colima start --vz --vz-rosetta --arch x86_64

// fail fast with a clear message before start
if err := util.AssertQemuImg(); err != nil {
    if vmType == "qemu" && environment.HostArch() != wantedArch {
        log.Fatal("cross-arch qemu VM needs qemu installed: brew install qemu")
    }
}

When it happens

Trigger: util.AssertQemuImg() fails (qemu-img/qemu-system not on PATH) while l.limaConf.VMType == limaconfig.QEMU and environment.HostArch() != l.limaConf.Arch — e.g. 'colima start --arch x86_64 --vm-type qemu' on Apple Silicon without qemu installed.

Common situations: Fresh Apple Silicon Mac starting an amd64 VM for Intel-only containers with the default QEMU driver; qemu removed by 'brew autoremove'; Linux host without the qemu-system package; CI image missing qemu.

Related errors

• error starting vm: %w
• cannot use vmType: '%s', error: %w
• minimum Lima version supported is %s, current version is %s
• unable to enable qemu %s emulation: %w
• %s not found, run 'brew install %s' to install

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