lima-vm/lima · error

failed to create driver instance: %w

Error message

failed to create driver instance: %w

What it means

Prepare() builds the VM driver for the instance via driverutil.CreateConfiguredDriver, which loads the driver for inst.VMType, applies configuration/defaults, and validates driver-specific constraints. If any of that fails (unsupported driver for the host OS, bad driver config, driver factory error), the error is wrapped as "failed to create driver instance".

Source

Thrown at pkg/instance/start.go:76

	case limatype.DARWIN:
		// macOS guests always need the guest agent for running fake-cloud-init
		needsGuestAgent = true
	case limatype.FREEBSD, limatype.WINDOWS:
		// guest agent is not implemented for FreeBSD and Windows yet
		needsGuestAgent = false
	default:
		needsGuestAgent = !*inst.Config.Plain
	}
	if needsGuestAgent && guestAgent == "" {
		var err error
		guestAgent, err = usrlocal.GuestAgentBinary(*inst.Config.OS, *inst.Config.Arch)
		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 {
		return nil, fmt.Errorf("failed to validate the instance YAML after filling defaults: %w", err)
	}

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

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

	// Migrate legacy disk layout (diffdisk → disk, ISO basedisk → iso)
	if err := driverutil.MigrateDiskLayout(inst.Dir); err != nil {
		return nil, err
	}

View on GitHub (pinned to dd909d0973)

Solutions

1. Check `vmType` in the instance's lima.yaml (limactl edit <inst>) is supported on your OS (qemu/vz per platform).
2. Read the inner %w error - it names the specific driver failure and fix that (e.g. install required virtualization components).
3. Recreate the instance with a valid driver: limactl delete <inst> && limactl create --vm-type=<valid> ...
4. Update Lima; older binaries may lack newer drivers like vz.

Example fix

// before (lima.yaml)
vmType: vz   # on Linux
// after
vmType: qemu  # or use vz only on macOS

inst, err := store.Inspect(ctx, instName)
if err != nil { return err }
// confirm the stored VMType is supported on this GOOS before starting
supported := map[string]bool{"qemu": true, "vz": runtime.GOOS == "darwin", "wsl2": runtime.GOOS == "windows"}
if !supported[string(inst.VMType)] {
  return fmt.Errorf("vmType %s not supported on %s", inst.VMType, runtime.GOOS)
}

func driverSupported(t limatype.VMType, goos string) bool {
  switch t {
  case "qemu": return true
  case "vz": return goos == "darwin"
  case "wsl2": return goos == "windows"
  default: return false
  }
}

When it happens

Trigger: Calling Start/StartWithPaths (limactl start, or start after create) where inst.VMType has no factory for the current GOOS, or the driver's configuration step fails (e.g. missing vz requirement, invalid cpuType, driverutil validation errors).

Common situations: Using vmType: vz on Linux or qemu on a build without it; editing instance YAML to an invalid driver field; running on Windows without WSL2 prerequisites; a stale instance dir whose stored VMType is unsupported by the current binary.

Related errors

• failed to create driver instance: %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
• external driver process exited before creating socket file

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