{"record":{"id":"6d00e3f308fc8b79","repo":"lima-vm/lima","slug":"could-not-find-firmware-for-q-hint-try-copying","errorCode":null,"errorMessage":"could not find firmware for %#q (hint: try copying the `edk-%s-code.fd` firmware to $HOME/.local/share/qemu/)","messagePattern":"could not find firmware for %#q \\(hint: try copying the `edk-(.+?)-code\\.fd` firmware to \\$HOME/\\.local/share/qemu/\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/qemu/qemu.go","lineNumber":1335,"sourceCode":"\t\t// Debian package \"qemu-efi-riscv64\"\n\t\tcandidates = append(candidates, \"/usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd\")\n\t\t// Fedora package \"edk2-riscv64\"\n\t\tcandidates = append(candidates, \"/usr/share/edk2/riscv/RISCV_VIRT_CODE.fd\")\n\t}\n\n\tlogrus.Debugf(\"firmware candidates = %v\", candidates)\n\n\tfor _, f := range candidates {\n\t\tif _, err := os.Stat(f); err == nil {\n\t\t\treturn f, nil\n\t\t}\n\t}\n\n\tif arch == limatype.X8664 {\n\t\treturn \"\", fmt.Errorf(\"could not find firmware for %#q (hint: try setting `firmware.legacyBIOS` to `true`)\", arch)\n\t}\n\tqemuArch := strings.TrimPrefix(filepath.Base(qemuExe), \"qemu-system-\")\n\treturn \"\", fmt.Errorf(\"could not find firmware for %#q (hint: try copying the `edk-%s-code.fd` firmware to $HOME/.local/share/qemu/)\", arch, qemuArch)\n}\n\nvar hasSMEDarwin = sync.OnceValue(func() bool {\n\tif runtime.GOOS != \"darwin\" || runtime.GOARCH != \"arm64\" {\n\t\treturn false\n\t}\n\t// golang.org/x/sys/cpu does not support inspecting the availability of SME yet\n\ts, err := osutil.Sysctl(context.Background(), \"hw.optional.arm.FEAT_SME\")\n\tif err != nil {\n\t\tlogrus.WithError(err).Debug(\"failed to check hw.optional.arm.FEAT_SME\")\n\t}\n\treturn s == \"1\"\n})\n\nfunc hasHostCPU(qemuVersion *semver.Version) bool {\n\tswitch runtime.GOOS {\n\tcase \"darwin\":\n\t\tif hasSMEDarwin() {","sourceCodeStart":1317,"sourceCodeEnd":1353,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/qemu/qemu.go#L1317-L1353","documentation":"For non-x86_64 architectures (aarch64, armv7l, riscv64), getFirmware() probes known EDK2 firmware paths, including $HOME/.local/share/qemu/edk-<qemuArch>-code.fd. If no firmware file is found, it errors and tells the user to place the matching edk-<arch>-code.fd file there. The arch name in the hint is derived from the qemu binary name (qemu-system-<arch>).","triggerScenarios":"Starting a QEMU instance with arch=aarch64/armv7l/riscv64 when no EDK2 firmware exists in the probed system paths or in $HOME/.local/share/qemu/edk-<arch>-code.fd.","commonSituations":"Apple Silicon Macs where an upgrade or nonstandard QEMU install removed/relocated edk2-arm-code.fd; missing edk2 package on Linux ARM hosts; custom qemu binaries whose basename prefix breaks the fallback lookup.","solutions":["Copy the matching firmware into $HOME/.local/share/qemu/ named `edk-<qemuArch>-code.fd` (e.g. `edk-aarch64-code.fd`), using the filename from the error message.","Install the distro edk2/QEMU firmware package (e.g. `apt install qemu-efi-aarch64`, `brew install qemu`).","Verify the qemu binary basename begins with `qemu-system-`; otherwise the derived qemuArch (and expected filename) will be wrong."],"exampleFix":"# before: firmware missing\n# after\ncp /usr/share/qemu/edk2-aarch64-code.fd $HOME/.local/share/qemu/edk-aarch64-code.fd","handlingStrategy":"fallback","validationCode":"qemuArch := \"aarch64\" // derive from binary name\nfw := filepath.Join(home, \".local\", \"share\", \"qemu\", fmt.Sprintf(\"edk-%s-code.fd\", qemuArch))\nif _, err := os.Stat(fw); err != nil {\n    // prompt user to install/copy the edk2 firmware before starting the VM\n}","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"could not find firmware\") && strings.Contains(err.Error(), \"edk-\") {\n    // copy the referenced edk-<arch>-code.fd into $HOME/.local/share/qemu/ then retry\n}","preventionTips":["Install the matching edk2 firmware package for the host arch (e.g. qemu-efi-aarch64, brew qemu).","Keep firmware copies in $HOME/.local/share/qemu/ named edk-<arch>-code.fd.","After QEMU upgrades, verify firmware paths still resolve before launching instances."],"tags":["qemu","firmware","edk2","aarch64"],"backgroundTag":"missing-firmware","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}