{"record":{"id":"89da49c858b39dc3","repo":"lima-vm/lima","slug":"failed-to-create-driver-instance-w","errorCode":null,"errorMessage":"failed to create driver instance: %w","messagePattern":"failed to create driver instance: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/hostagent/hostagent.go","lineNumber":171,"sourceCode":"\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tvar udpDNSLocalPort, tcpDNSLocalPort int\n\tif limayaml.HostResolverEnabled(inst.Config) {\n\t\tudpDNSLocalPort, err = freeport.UDP()\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\ttcpDNSLocalPort, err = freeport.TCP()\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\n\tlimaDriver, err := driverutil.CreateConfiguredDriver(ctx, inst, sshLocalPort)\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\tsshLocalPort = inst.SSHLocalPort\n\n\tinfo := limaDriver.Info(ctx)\n\tvSockPort := info.VsockPort\n\tvirtioPort := info.VirtioPort\n\tnoCloudInit := info.Features.NoCloudInit\n\trosettaEnabled := info.Features.RosettaEnabled\n\trosettaBinFmt := info.Features.RosettaBinFmt\n\n\t// Disable Rosetta in Plain mode\n\tif *inst.Config.Plain {\n\t\trosettaEnabled = false\n\t\trosettaBinFmt = false\n\t}","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/hostagent/hostagent.go#L153-L189","documentation":"HostAgent.New calls driverutil.CreateConfiguredDriver to instantiate the VM driver (qemu/vz/wsl2) with the instance config and SSH local port. If driver creation fails for any reason (unsupported driver, missing binary, bad config), the underlying error is wrapped with this message.","triggerScenarios":"limactl start/start-instance resolves the instance and calls hostagent.New when the configured driver cannot be constructed — bad driver field, driver binary missing, driver-specific validation failure inside CreateConfiguredDriver.","commonSituations":"vmType set to 'vz' on non-macOS or old macOS; qemu-system-* binaries not installed or not on PATH; driver option invalid for that backend; corrupted instance config pointing at a nonexistent driver.","solutions":["Read the wrapped underlying error for the root cause (missing binary, validation, etc.)","Verify vmType in the instance's lima.yaml is supported on your OS (qemu or vz on macOS, wsl2 on Windows)","Install the required driver tooling (e.g. qemu on Linux: apt install qemu-system-x86) and ensure it is on PATH","Recreate the instance with limactl delete + limactl start if the stored config is corrupted"],"exampleFix":"// before (lima.yaml)\nvmType: \"vz\"   # on Linux/older macOS\n// after\nvmType: \"qemu\"","handlingStrategy":"validation","validationCode":"// before starting, check driver support\ncfg, _ := os.ReadFile(filepath.Join(instDir, \"lima.yaml\"))\nvar m map[string]any\n_ = yaml.Unmarshal(cfg, &m)\nvmType, _ := m[\"vmType\"].(string)\nif vmType == \"vz\" && runtime.GOOS != \"darwin\" {\n\treturn fmt.Errorf(\"vmType vz requires macOS\")\n}\nif vmType == \"qemu\" {\n\tif _, err := exec.LookPath(\"qemu-system-x86_64\"); err != nil {\n\t\treturn fmt.Errorf(\"qemu not installed/on PATH\")\n\t}\n}","typeGuard":null,"tryCatchPattern":"ha, err := hostagent.New(ctx, inst, sshLocalPort, ...)\nif err != nil {\n\tif strings.Contains(err.Error(), \"failed to create driver instance\") {\n\t\tlog.Fatalf(\"driver problem: %v — check vmType and installed driver binaries\", err)\n\t}\n\treturn err\n}","preventionTips":["Pin vmType to a value supported on your host OS","Install and PATH-verify driver binaries (qemu-system-*) before limactl start","Run 'limactl validate' on templates/instance YAML","Keep limactl and instance config versions aligned"],"tags":["driver","vm","startup"],"backgroundTag":"driver-creation-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}