{"record":{"id":"506d49bd365c6115","repo":"lima-vm/lima","slug":"failed-to-create-driver-instance-w-506d49","errorCode":null,"errorMessage":"failed to create driver instance: %w","messagePattern":"failed to create driver instance: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/instance/start.go","lineNumber":76,"sourceCode":"\tcase limatype.DARWIN:\n\t\t// macOS guests always need the guest agent for running fake-cloud-init\n\t\tneedsGuestAgent = true\n\tcase limatype.FREEBSD, limatype.WINDOWS:\n\t\t// guest agent is not implemented for FreeBSD and Windows yet\n\t\tneedsGuestAgent = false\n\tdefault:\n\t\tneedsGuestAgent = !*inst.Config.Plain\n\t}\n\tif needsGuestAgent && guestAgent == \"\" {\n\t\tvar err error\n\t\tguestAgent, err = usrlocal.GuestAgentBinary(*inst.Config.OS, *inst.Config.Arch)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\tlimaDriver, err := driverutil.CreateConfiguredDriver(ctx, inst, 0)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create driver instance: %w\", err)\n\t}\n\tif err := limayaml.Validate(inst.Config, true); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to validate the instance YAML after filling defaults: %w\", err)\n\t}\n\n\tif err := limaDriver.Validate(ctx); err != nil {\n\t\treturn nil, err\n\t}\n\n\tif err := limaDriver.Create(ctx); err != nil {\n\t\treturn nil, err\n\t}\n\n\t// Migrate legacy disk layout (diffdisk → disk, ISO basedisk → iso)\n\tif err := driverutil.MigrateDiskLayout(inst.Dir); err != nil {\n\t\treturn nil, err\n\t}\n","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/instance/start.go#L58-L94","documentation":"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\".","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check `vmType` in the instance's lima.yaml (limactl edit <inst>) is supported on your OS (qemu/vz per platform).","Read the inner %w error - it names the specific driver failure and fix that (e.g. install required virtualization components).","Recreate the instance with a valid driver: limactl delete <inst> && limactl create --vm-type=<valid> ...","Update Lima; older binaries may lack newer drivers like vz."],"exampleFix":"// before (lima.yaml)\nvmType: vz   # on Linux\n// after\nvmType: qemu  # or use vz only on macOS","handlingStrategy":"validation","validationCode":"inst, err := store.Inspect(ctx, instName)\nif err != nil { return err }\n// confirm the stored VMType is supported on this GOOS before starting\nsupported := map[string]bool{\"qemu\": true, \"vz\": runtime.GOOS == \"darwin\", \"wsl2\": runtime.GOOS == \"windows\"}\nif !supported[string(inst.VMType)] {\n  return fmt.Errorf(\"vmType %s not supported on %s\", inst.VMType, runtime.GOOS)\n}","typeGuard":"func driverSupported(t limatype.VMType, goos string) bool {\n  switch t {\n  case \"qemu\": return true\n  case \"vz\": return goos == \"darwin\"\n  case \"wsl2\": return goos == \"windows\"\n  default: return false\n  }\n}","tryCatchPattern":null,"preventionTips":["Keep vmType consistent with the host OS in templates and lima.yaml","After moving instance dirs between machines, re-check vmType","Update Lima when adopting new drivers (vz, wsl2)","Read the wrapped inner error - it names the exact driver failure"],"tags":["driver","vmtype","startup"],"backgroundTag":"vm-driver-creation-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}