abiosoft/colima · error

error installing binfmt: %w

Error message

error installing binfmt: %w

What it means

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'.

Source

Thrown at core/core.go:32

)

const limaVersion = "v0.18.0" // minimum Lima version supported

type (
	hostActions  = environment.HostActions
	guestActions = environment.GuestActions
)

// SetupBinfmt downloads and install binfmt
func SetupBinfmt(host hostActions, guest guestActions, arch environment.Arch) error {
	qemuArch := environment.AARCH64
	if arch.Value().GoArch() == "arm64" {
		qemuArch = environment.X8664
	}

	install := func() error {
		if err := guest.Run("sh", "-c", "sudo QEMU_PRESERVE_ARGV0=1 /usr/bin/binfmt --install 386,"+qemuArch.GoArch()); err != nil {
			return fmt.Errorf("error installing binfmt: %w", err)
		}
		return nil
	}

	// validate binfmt
	if err := guest.RunQuiet("command", "-v", "binfmt"); err != nil {
		return fmt.Errorf("binfmt not found: %w", err)
	}

	return install()
}

// LimaVersionSupported checks if the currently installed Lima version is supported.
func LimaVersionSupported() error {
	var values struct {
		Version string `json:"version"`
	}
	var buf bytes.Buffer

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Verify guest internet (e.g. 'colima ssh -- curl -sI https://dl.google.com'), fix VM network or DNS, then retry 'colima start'
2. Retry the start once the VM has settled; transient first-boot failures are common
3. Run the command manually to see the raw failure: colima ssh -- sudo QEMU_PRESERVE_ARGV0=1 /usr/bin/binfmt --install 386,aarch64
4. If emulation is not required, start without --arch to run native architecture containers

Example fix

# before
colima start --arch aarch64   # error installing binfmt

# after fixing VM network
colima delete && colima start --arch aarch64

// Verify guest network reachability before triggering binfmt install.
if err := guest.RunQuiet("curl", "-fsI", "https://dl.google.com"); err != nil {
    return fmt.Errorf("guest has no internet, binfmt install will fail: %w", err)
}

var err error
for attempt := 1; attempt <= 3; attempt++ {
    if err = core.SetupBinfmt(host, guest, arch); err == nil {
        break
    }
    if !strings.Contains(err.Error(), "error installing binfmt") {
        break // non-transient cause, stop retrying
    }
    time.Sleep(time.Duration(attempt) * 5 * time.Second) // first-boot network settling
}

When it happens

Trigger: '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.

Common situations: 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.

Related errors

• binfmt not found: %w
• unable to enable qemu %s emulation: %w
• error provisioning %s: %w
• no available port found in range %d-%d
• port %d is already in use

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