lima-vm/lima · error

failed to create driver instance: %w

Error message

failed to create driver instance: %w

What it means

pkg/instance.Create failed while constructing the VM driver via driverutil.CreateConfiguredDriver. This happens after the instance directory was created and lima.yml was persisted, so the config itself passed the initial validation; the driver layer rejected instantiation (e.g. driver not compiled in for the platform, external driver binary missing, or driver-specific config error).

Source

Thrown at pkg/instance/create.go:92

			_ = os.RemoveAll(instDir)
		}
	}()

	if err := os.WriteFile(filePath, instConfig, 0o644); err != nil {
		return nil, err
	}
	if err := os.WriteFile(filepath.Join(instDir, filenames.LimaVersion), []byte(version.Version), 0o444); err != nil {
		return nil, err
	}

	inst, err := store.Inspect(ctx, instName)
	if err != nil {
		return nil, err
	}

	limaDriver, err := driverutil.CreateConfiguredDriver(ctx, inst, 0)
	if err != nil {
		return nil, fmt.Errorf("failed to create driver instance: %w", err)
	}
	if err := limayaml.Validate(inst.Config, true); err != nil {
		if !saveBrokenYAML {
			return nil, err
		}
		rejectedYAML := "lima.REJECTED.yaml"
		if writeErr := os.WriteFile(rejectedYAML, instConfig, 0o644); writeErr != nil {
			return nil, fmt.Errorf("the YAML is invalid, attempted to save the buffer as %#q but failed: %w: %w", rejectedYAML, writeErr, err)
		}
		return nil, fmt.Errorf("the YAML is invalid, saved the buffer as %#q: %w", rejectedYAML, err)
	}
	if err := cidata.GenerateCloudConfig(ctx, instDir, instName, inst.Config); err != nil {
		return nil, err
	}

	if err := limaDriver.Create(ctx); err != nil {
		return nil, err
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Read the wrapped driver error; it names the driver that failed to load or configure.
2. Check that your lima.yml vmType is supported on the host OS (`limactl create --vm-type=vz ...` only on macOS, etc.).
3. If using an external driver, verify the driver binary is installed and on PATH / in the expected location.
4. Rebuild with the right build tags (`make native`) if drivers were excluded at compile time.

Example fix

// before (lima.yml on Linux)
vmType: "vz"
// after
vmType: "qemu"

// confirm vmType support on this host before Create
switch cfg.VMType {
case "vz":
    if runtime.GOOS != "darwin" { return errors.New("vz requires macOS") }
case "wsl2":
    if runtime.GOOS != "windows" { return errors.New("wsl2 requires Windows") }
}

inst, err := instance.Create(ctx, name, buf, false)
if err != nil {
    if strings.Contains(err.Error(), "failed to create driver instance") {
        // fall back to a supported vmType or surface install instructions
    }
    return err
}

When it happens

Trigger: instance.Create calls driverutil.CreateConfiguredDriver(ctx, inst, 0) at create.go:90 and it returns an error — e.g. vmType has no driver registered on the host OS, an external driver binary cannot be located/launched, or driver.Load/Configure fails on the instance config.

Common situations: Using vmType like qemu/vz/wsl2 on a platform where it is unavailable (e.g. vz on Linux), building limactl without a driver tag, or a broken external-driver installation.

Related errors

• failed to resolve vm for %#q: %w
• failed to get boot scripts: %w
• invalid boot script filename %#q: must be in format 'boot.<O
• unimplemented by the krunkit driver
• inspect status command failed: %w

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