lima-vm/lima · critical

failed to create driver instance: %w

Error message

failed to create driver instance: %w

What it means

HostAgent.New calls driverutil.CreateConfiguredDriver to instantiate the VM driver (qemu/vz/wsl2) with the instance config and SSH local port. If driver creation fails for any reason (unsupported driver, missing binary, bad config), the underlying error is wrapped with this message.

Source

Thrown at pkg/hostagent/hostagent.go:171

	if err != nil {
		return nil, err
	}

	var udpDNSLocalPort, tcpDNSLocalPort int
	if limayaml.HostResolverEnabled(inst.Config) {
		udpDNSLocalPort, err = freeport.UDP()
		if err != nil {
			return nil, err
		}
		tcpDNSLocalPort, err = freeport.TCP()
		if err != nil {
			return nil, err
		}
	}

	limaDriver, err := driverutil.CreateConfiguredDriver(ctx, inst, sshLocalPort)
	if err != nil {
		return nil, fmt.Errorf("failed to create driver instance: %w", err)
	}
	if err := limayaml.Validate(inst.Config, true); err != nil {
		return nil, fmt.Errorf("failed to validate the instance YAML after filling defaults: %w", err)
	}
	sshLocalPort = inst.SSHLocalPort

	info := limaDriver.Info(ctx)
	vSockPort := info.VsockPort
	virtioPort := info.VirtioPort
	noCloudInit := info.Features.NoCloudInit
	rosettaEnabled := info.Features.RosettaEnabled
	rosettaBinFmt := info.Features.RosettaBinFmt

	// Disable Rosetta in Plain mode
	if *inst.Config.Plain {
		rosettaEnabled = false
		rosettaBinFmt = false
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Read the wrapped underlying error for the root cause (missing binary, validation, etc.)
2. Verify vmType in the instance's lima.yaml is supported on your OS (qemu or vz on macOS, wsl2 on Windows)
3. Install the required driver tooling (e.g. qemu on Linux: apt install qemu-system-x86) and ensure it is on PATH
4. Recreate the instance with limactl delete + limactl start if the stored config is corrupted

Example fix

// before (lima.yaml)
vmType: "vz"   # on Linux/older macOS
// after
vmType: "qemu"

// before starting, check driver support
cfg, _ := os.ReadFile(filepath.Join(instDir, "lima.yaml"))
var m map[string]any
_ = yaml.Unmarshal(cfg, &m)
vmType, _ := m["vmType"].(string)
if vmType == "vz" && runtime.GOOS != "darwin" {
	return fmt.Errorf("vmType vz requires macOS")
}
if vmType == "qemu" {
	if _, err := exec.LookPath("qemu-system-x86_64"); err != nil {
		return fmt.Errorf("qemu not installed/on PATH")
	}
}

ha, err := hostagent.New(ctx, inst, sshLocalPort, ...)
if err != nil {
	if strings.Contains(err.Error(), "failed to create driver instance") {
		log.Fatalf("driver problem: %v — check vmType and installed driver binaries", err)
	}
	return err
}

When it happens

Trigger: limactl start/start-instance resolves the instance and calls hostagent.New when the configured driver cannot be constructed — bad driver field, driver binary missing, driver-specific validation failure inside CreateConfiguredDriver.

Common situations: vmType set to 'vz' on non-macOS or old macOS; qemu-system-* binaries not installed or not on PATH; driver option invalid for that backend; corrupted instance config pointing at a nonexistent driver.

Related errors

• failed to create driver instance: %w
• failed to rsync to the guest %w
• failed to get boot scripts: %w
• invalid boot script filename %#q: must be in format 'boot.<O
• failed to write driver PID file: %w

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/89da49c858b39dc3. Report an issue: GitHub.