{"record":{"id":"964bd0b615ebb43e","repo":"abiosoft/colima","slug":"qemu-is-required-to-emulate-s-w","errorCode":null,"errorMessage":"qemu is required to emulate %s: %w","messagePattern":"qemu is required to emulate (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"environment/vm/lima/lima.go","lineNumber":382,"sourceCode":"\t\t// if additional disk is present, then it must've been formatted correctly.\n\t\tif err := store.Set(func(s *store.Store) {\n\t\t\ts.DiskFormatted = true\n\t\t}); err != nil {\n\t\t\t// not fatal, but should be logged\n\t\t\tlogrus.Warnln(fmt.Errorf(\"error persisting store settings: %w\", err))\n\t\t}\n\n\t\treturn nil\n\t})\n\n}\n\nfunc (l *limaVM) assertQemu() error {\n\t// assert qemu requirement\n\tsameArchitecture := environment.HostArch() == l.limaConf.Arch\n\tif err := util.AssertQemuImg(); err != nil && l.limaConf.VMType == limaconfig.QEMU {\n\t\tif !sameArchitecture {\n\t\t\treturn fmt.Errorf(\"qemu is required to emulate %s: %w\", l.limaConf.Arch, err)\n\t\t}\n\t\treturn err\n\t}\n\treturn nil\n}\n\nconst envLimaSSHPortForwarder = \"LIMA_SSH_PORT_FORWARDER\"\n\nfunc (l *limaVM) prepareHost(conf config.Config) {\n\tuseSSHPortForwarder := conf.PortForwarder != \"grpc\"\n\n\tl.host = l.host.WithEnv(envLimaSSHPortForwarder + \"=\" + strconv.FormatBool(useSSHPortForwarder))\n}\n","sourceCodeStart":364,"sourceCodeEnd":396,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/environment/vm/lima/lima.go#L364-L396","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install qemu: 'brew install qemu' (macOS) or 'apt-get install qemu-system' / 'dnf install qemu-system-*' (Linux)","On Apple Silicon prefer virtualization: 'colima start --vz-rosetta --vz' which runs amd64 containers via Rosetta without full emulation","If you do not need another architecture, drop --arch so it matches the host","Verify with 'qemu-img --version' that PATH resolution works in the shell/launchd context"],"exampleFix":"# before\ncolima start --arch x86_64   # fails: qemu is required to emulate x86_64\n# after (Apple Silicon, no qemu needed)\ncolima start --vz --vz-rosetta --arch x86_64","handlingStrategy":"validation","validationCode":"// fail fast with a clear message before start\nif err := util.AssertQemuImg(); err != nil {\n    if vmType == \"qemu\" && environment.HostArch() != wantedArch {\n        log.Fatal(\"cross-arch qemu VM needs qemu installed: brew install qemu\")\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install qemu before any cross-arch QEMU start","Prefer --vz-rosetta on Apple Silicon for amd64 containers — no qemu needed","CI: add 'qemu-img --version' as an early sanity step in the pipeline"],"tags":["qemu","emulation","architecture","dependencies","startup"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}