lima-vm/lima · error

vmType %#q is not a registered driver

Error message

vmType %#q is not a registered driver

What it means

ResolveVMType validates the vmType in a LimaYAML after applying defaults. It accepts built-in VM types unconditionally and otherwise requires the type to be present in the external driver registry. This error means the YAML explicitly names a VM type Lima cannot resolve at all — neither built-in nor a discovered external driver.

Source

Thrown at pkg/driverutil/vm.go:40

// It validates the VMType is a known type (built-in or discovered external driver)
// but does NOT require the driver to be available on the current platform.
func ResolveVMType(y *limatype.LimaYAML) error {
	if y.VMType == nil {
		y.VMType = new(limatype.DefaultDriver())
		if y.Arch != nil && !limatype.IsNativeArch(*y.Arch) {
			y.VMType = new(limatype.DefaultNonNativeArchDriver())
		}
	}

	// Accept built-in VMType regardless of current platform.
	if slices.Contains(limatype.VMTypes, *y.VMType) {
		return nil
	}

	// Also accept external drivers discovered in the registry.
	_, _, exists := registry.Get(*y.VMType)
	if !exists {
		return fmt.Errorf("vmType %#q is not a registered driver", *y.VMType)
	}

	return nil
}

func InspectStatus(ctx context.Context, inst *limatype.Instance) (string, error) {
	if inst == nil || inst.Config == nil || inst.Config.VMType == nil {
		return "", errors.New("instance or its configuration is not properly initialized")
	}

	extDriver, intDriver, exists := registry.Get(*inst.Config.VMType)
	if !exists {
		return "", fmt.Errorf("unknown or unsupported VM type: %s", *inst.Config.VMType)
	}

	if extDriver != nil {
		status, err := handleInspectStatusAction(ctx, inst, extDriver.Path)
		if err != nil {

View on GitHub (pinned to dd909d0973)

Solutions

1. Correct the vmType value in the template/lima.yaml to a built-in type: qemu, vz, wsl2
2. Install the external driver providing that vmType so registry discovery finds it
3. Remove the explicit vmType line and let Lima pick the default for your platform and arch
4. Upgrade limactl to match the template's expected Lima version

Example fix

// before: template.yaml
vmType: "virtio" // not registered
// after
vmType: "qemu" // or remove the line entirely

y, err := limayaml.Load(b, "template.yaml")
if err != nil {
    return err
}
if err := driverutil.ResolveVMType(y); err != nil {
    return err // surfaces unknown vmType before any VM work
}

func vmTypeRegistered(t string) bool {
    return slices.Contains(limatype.VMTypes, t) || func() bool {
        _, _, ok := registry.Get(t)
        return ok
    }()
}

if err := driverutil.ResolveVMType(y); err != nil {
    log.Warnf("%v; falling back to default driver", err)
    y.VMType = nil
    _ = driverutil.ResolveVMType(y)
}

When it happens

Trigger: Calling ResolveVMType (via limactl start template processing, fillDefaults, edit, restart, clone/rename, or YAML location listing) on a config where y.VMType is set to a string that is neither in limatype.VMTypes nor registered by any external driver plugin.

Common situations: Copy-pasting a template that uses an external driver you never installed; typos like "Qemu" or "vz" on a build without VZ; using a template from Lima main with an older local build; missing external driver discovery (wrong install path).

Related errors

• unknown or unsupported VM type: %s
• disk format %#q not supported, use `qcow2` or `raw` instead
• the YAML is invalid, attempted to save the buffer as %#q but
• the YAML is invalid, saved the buffer as %#q: %w
• invalid port forward format %#q, expected HOST:GUEST or HOST

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