lima-vm/lima · error

failed to create driver instance: %w

Error message

failed to create driver instance: %w

What it means

snapshot.Del instantiates the instance's configured driver (via driverutil.CreateConfiguredDriver) before delegating to the driver's DeleteSnapshot. When driver construction fails — wrong/missing driver, failed instance config validation after filling defaults, or driver initialization errors — the failure is wrapped as "failed to create driver instance". The snapshot was not deleted; the operation aborts before touching the VM.

Source

Thrown at pkg/snapshot/snapshot.go:19

// SPDX-FileCopyrightText: Copyright The Lima Authors
// SPDX-License-Identifier: Apache-2.0

package snapshot

import (
	"context"
	"fmt"

	"github.com/lima-vm/lima/v2/pkg/driver"
	"github.com/lima-vm/lima/v2/pkg/driverutil"
	"github.com/lima-vm/lima/v2/pkg/limatype"
	"github.com/lima-vm/lima/v2/pkg/limayaml"
)

func Del(ctx context.Context, inst *limatype.Instance, tag string) error {
	limaDriver, err := createConfiguredDriver(ctx, inst)
	if err != nil {
		return fmt.Errorf("failed to create driver instance: %w", err)
	}

	return limaDriver.DeleteSnapshot(ctx, tag)
}

func Save(ctx context.Context, inst *limatype.Instance, tag string) error {
	limaDriver, err := createConfiguredDriver(ctx, inst)
	if err != nil {
		return fmt.Errorf("failed to create driver instance: %w", err)
	}
	return limaDriver.CreateSnapshot(ctx, tag)
}

func Load(ctx context.Context, inst *limatype.Instance, tag string) error {
	limaDriver, err := createConfiguredDriver(ctx, inst)
	if err != nil {
		return fmt.Errorf("failed to create driver instance: %w", err)
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Read the wrapped cause in the error chain; if it says the driver is unknown/missing, reinstall the external driver or ensure it is discoverable (LIMA_DRIVERS / libexec dir, named lima-driver-<name>).
2. Run `limactl validate <instance-config>` or inspect ~/.lima/<instance>/lima.yaml; fix any invalid fields so limayaml.Validate passes.
3. If the driver is permanently gone, remove stale snapshot state manually (delete the snapshot entries under the instance directory / qcow2 internal snapshots via `qemu-img snapshot -d`) rather than via limactl.

Example fix

// before: instance uses driver "qemu-ext" which is uninstalled
//   limactl snapshot delete inst tag  -> failed to create driver instance
// after
//   # reinstall the driver so it is discoverable:
//   cp lima-driver-qemu-ext ~/.local/libexec/lima/ && chmod +x ~/.local/libexec/lima/lima-driver-qemu-ext
//   limactl snapshot delete inst tag

// Before snapshot operations, check the instance's driver is registered and config is valid:
// limactl list <inst> && limactl validate ~/.lima/<inst>/lima.yaml
// Confirm the driver binary exists: ls ~/.local/libexec/lima/lima-driver-* /usr/local/libexec/lima/lima-driver-*

err := snapshot.Del(ctx, inst, tag)
if err != nil {
	if strings.Contains(err.Error(), "failed to create driver instance") {
		// surface the wrapped cause: unknown driver / invalid YAML
		return fmt.Errorf("cannot delete snapshot: driver for instance %q unavailable: %w (reinstall the driver or fix lima.yaml)", inst.Name, err)
	}
	return err
}

When it happens

Trigger: Calling snapshot.Del (limactl snapshot delete) when CreateConfiguredDriver returns an error: the instance's recorded driver name has no registered driver binary (external driver missing), the instance YAML fails limayaml.Validate after defaults are filled, or the driver's own initialization (e.g. reading instance state) fails.

Common situations: Deleting snapshots of an instance created with an external driver that was since uninstalled or is not on the driver path; instance directory whose lima.yaml was hand-edited into an invalid state; running the command against an instance whose config predates a schema change.

Related errors

• instance %q not found
• instance %#q not found
• failed to delete instance %#q: %w
• instance %#q directory %#q exists but its %#q could not be r
• failed to inspect instance %#q: %w

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