{"record":{"id":"f827a79a21725768","repo":"abiosoft/colima","slug":"error-installing-binfmt-w","errorCode":null,"errorMessage":"error installing binfmt: %w","messagePattern":"error installing binfmt: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/core.go","lineNumber":32,"sourceCode":")\n\nconst limaVersion = \"v0.18.0\" // minimum Lima version supported\n\ntype (\n\thostActions  = environment.HostActions\n\tguestActions = environment.GuestActions\n)\n\n// SetupBinfmt downloads and install binfmt\nfunc SetupBinfmt(host hostActions, guest guestActions, arch environment.Arch) error {\n\tqemuArch := environment.AARCH64\n\tif arch.Value().GoArch() == \"arm64\" {\n\t\tqemuArch = environment.X8664\n\t}\n\n\tinstall := func() error {\n\t\tif err := guest.Run(\"sh\", \"-c\", \"sudo QEMU_PRESERVE_ARGV0=1 /usr/bin/binfmt --install 386,\"+qemuArch.GoArch()); err != nil {\n\t\t\treturn fmt.Errorf(\"error installing binfmt: %w\", err)\n\t\t}\n\t\treturn nil\n\t}\n\n\t// validate binfmt\n\tif err := guest.RunQuiet(\"command\", \"-v\", \"binfmt\"); err != nil {\n\t\treturn fmt.Errorf(\"binfmt not found: %w\", err)\n\t}\n\n\treturn install()\n}\n\n// LimaVersionSupported checks if the currently installed Lima version is supported.\nfunc LimaVersionSupported() error {\n\tvar values struct {\n\t\tVersion string `json:\"version\"`\n\t}\n\tvar buf bytes.Buffer","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/abiosoft/colima/blob/c3a5f9184d83a197184f897a9f07eb3c01b3bc88/core/core.go#L14-L50","documentation":"SetupBinfmt registers QEMU binfmt_misc handlers so cross-architecture containers can run under emulation. It executes 'sudo QEMU_PRESERVE_ARGV0=1 /usr/bin/binfmt --install 386,<target>' inside the guest via guest.Run, where target is the opposite of the host arch selection; any non-zero exit or guest-channel failure is wrapped as 'error installing binfmt'.","triggerScenarios":"'colima start --arch aarch64' on an x86_64 host (or --arch x86_64 on ARM) when the in-guest binfmt install fails: no outbound guest network to fetch qemu-user-static binaries, sudo policy blocking the command, /usr/bin/binfmt erroring, or the guest run channel being broken.","commonSituations":"Cross-arch development such as building arm64 images on Intel machines; VPN or DNS problems inside the VM; first-boot races where networking is not yet settled; customized guest images lacking a working binfmt helper.","solutions":["Verify guest internet (e.g. 'colima ssh -- curl -sI https://dl.google.com'), fix VM network or DNS, then retry 'colima start'","Retry the start once the VM has settled; transient first-boot failures are common","Run the command manually to see the raw failure: colima ssh -- sudo QEMU_PRESERVE_ARGV0=1 /usr/bin/binfmt --install 386,aarch64","If emulation is not required, start without --arch to run native architecture containers"],"exampleFix":"# before\ncolima start --arch aarch64   # error installing binfmt\n\n# after fixing VM network\ncolima delete && colima start --arch aarch64","handlingStrategy":"retry","validationCode":"// Verify guest network reachability before triggering binfmt install.\nif err := guest.RunQuiet(\"curl\", \"-fsI\", \"https://dl.google.com\"); err != nil {\n    return fmt.Errorf(\"guest has no internet, binfmt install will fail: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"var err error\nfor attempt := 1; attempt <= 3; attempt++ {\n    if err = core.SetupBinfmt(host, guest, arch); err == nil {\n        break\n    }\n    if !strings.Contains(err.Error(), \"error installing binfmt\") {\n        break // non-transient cause, stop retrying\n    }\n    time.Sleep(time.Duration(attempt) * 5 * time.Second) // first-boot network settling\n}","preventionTips":["Ensure the VM has working DNS and outbound access before starting cross-arch flows","Recreate the VM with 'colima delete' when provisioning repeatedly fails","Prefer native-arch VMs; only use --arch when emulation is required"],"tags":["binfmt","cross-arch","emulation","guest","network"],"backgroundTag":null,"analyzedSha":"c3a5f9184d83a197184f897a9f07eb3c01b3bc88","analyzedAt":"2026-08-15T18:58:08.334Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}