{"record":{"id":"601fadf013d6c609","repo":"lima-vm/lima","slug":"failed-to-create-driver-instance-w-601fad","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/create.go","lineNumber":92,"sourceCode":"\t\t\t_ = os.RemoveAll(instDir)\n\t\t}\n\t}()\n\n\tif err := os.WriteFile(filePath, instConfig, 0o644); err != nil {\n\t\treturn nil, err\n\t}\n\tif err := os.WriteFile(filepath.Join(instDir, filenames.LimaVersion), []byte(version.Version), 0o444); err != nil {\n\t\treturn nil, err\n\t}\n\n\tinst, err := store.Inspect(ctx, instName)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\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\tif !saveBrokenYAML {\n\t\t\treturn nil, err\n\t\t}\n\t\trejectedYAML := \"lima.REJECTED.yaml\"\n\t\tif writeErr := os.WriteFile(rejectedYAML, instConfig, 0o644); writeErr != nil {\n\t\t\treturn nil, fmt.Errorf(\"the YAML is invalid, attempted to save the buffer as %#q but failed: %w: %w\", rejectedYAML, writeErr, err)\n\t\t}\n\t\treturn nil, fmt.Errorf(\"the YAML is invalid, saved the buffer as %#q: %w\", rejectedYAML, err)\n\t}\n\tif err := cidata.GenerateCloudConfig(ctx, instDir, instName, inst.Config); 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}","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/instance/create.go#L74-L110","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped driver error; it names the driver that failed to load or configure.","Check that your lima.yml vmType is supported on the host OS (`limactl create --vm-type=vz ...` only on macOS, etc.).","If using an external driver, verify the driver binary is installed and on PATH / in the expected location.","Rebuild with the right build tags (`make native`) if drivers were excluded at compile time."],"exampleFix":"// before (lima.yml on Linux)\nvmType: \"vz\"\n// after\nvmType: \"qemu\"","handlingStrategy":"validation","validationCode":"// confirm vmType support on this host before Create\nswitch cfg.VMType {\ncase \"vz\":\n    if runtime.GOOS != \"darwin\" { return errors.New(\"vz requires macOS\") }\ncase \"wsl2\":\n    if runtime.GOOS != \"windows\" { return errors.New(\"wsl2 requires Windows\") }\n}","typeGuard":null,"tryCatchPattern":"inst, err := instance.Create(ctx, name, buf, false)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to create driver instance\") {\n        // fall back to a supported vmType or surface install instructions\n    }\n    return err\n}","preventionTips":["Pin vmType to a value valid for the host OS","Build limactl via `make native` so all platform drivers are present","Keep external driver binaries installed and on PATH"],"tags":["driver","vm-type","instance-create"],"backgroundTag":"driver-initialization-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}