{"record":{"id":"a844a70de3fbf4ee","repo":"lima-vm/lima","slug":"timed-out-waiting-for-external-driver-to-create-so","errorCode":null,"errorMessage":"timed out waiting for external driver to create socket file","messagePattern":"timed out waiting for external driver to create socket file","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/external/server/server.go","lineNumber":270,"sourceCode":"\t\t\t\t\t\tdriverLogger.Errorf(\"Failed to kill external driver process after client creation failure: %v\", err)\n\t\t\t\t\t}\n\t\t\t\t\t<-procExit\n\t\t\t\t\treturn fmt.Errorf(\"failed to create driver client: %w\", err)\n\t\t\t\t}\n\t\t\t\tdriverLogger.Debugf(\"External driver %s started successfully\", extDriver.Name)\n\t\t\t\treturn nil\n\t\t\t}\n\t\tcase waitErr := <-procExit:\n\t\t\tif waitErr == nil {\n\t\t\t\treturn errors.New(\"external driver process exited before creating socket file\")\n\t\t\t}\n\t\t\treturn fmt.Errorf(\"external driver process exited before creating socket file: %w\", waitErr)\n\t\tcase <-socketWaitCtx.Done():\n\t\t\tif err := cmd.Process.Kill(); err != nil {\n\t\t\t\tdriverLogger.Errorf(\"Failed to kill external driver process after socket wait timeout: %v\", err)\n\t\t\t}\n\t\t\t<-procExit\n\t\t\treturn errors.New(\"timed out waiting for external driver to create socket file\")\n\t\t}\n\t}\n}\n\n// Stop finds and stops any external driver server processes in the given\n// instance directory using PID files. If force is true, SIGKILL is sent;\n// otherwise SIGTERM is sent and we wait for the process to exit.\n// Also cleans up PID files and socket files.\nfunc Stop(instDir string, force bool) {\n\tlogrus.Debugf(\"Stopping external driver server in instance directory %s\", instDir)\n\tpidPattern := filepath.Join(instDir, \"*.drv.pid\")\n\tfiles, _ := filepath.Glob(pidPattern)\n\tfor _, pidFile := range files {\n\t\tpidData, err := os.ReadFile(pidFile)\n\t\tif err != nil {\n\t\t\t_ = os.Remove(pidFile)\n\t\t\tcontinue\n\t\t}","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/external/server/server.go#L252-L288","documentation":"lima gives the external driver a bounded window (socketWaitCtx) to create its socket file. If the context deadline fires first, Start kills the driver process, reaps it, and returns this timeout error. Unlike 282/283 the process was still alive — it just never became reachable in time.","triggerScenarios":"The driver process runs but does not create the expected socket before the context deadline — slow/overloaded host, driver stuck initializing (e.g. blocked on network or a lock), or a driver that listens on a different path than lima expects.","commonSituations":"Heavily loaded CI runner delaying startup past the deadline; driver plugin with a different socket-path convention (version skew); NFS/odd filesystem where the socket creation isn't visible; driver hanging on a stale lock file in the instance dir.","solutions":["Retry the start; transient slowness is the most common cause","Capture driver logs with debug enabled to find where initialization hangs","Remove stale state in the instance dir (locks, old sockets) and retry","Upgrade or replace the driver plugin so its socket path matches what lima expects"],"exampleFix":"// before: stale lock makes driver hang past timeout\n$ limactl start myvm  # timed out waiting for external driver to create socket file\n// after\n$ rm -f ~/.lima/myvm/*.lock ~/.lima/myvm/*.sock\n$ limactl start myvm","handlingStrategy":"retry","validationCode":"// pre-check: no stale sockets/locks in the instance dir\nmatches, _ := filepath.Glob(filepath.Join(instanceDir, \"*.sock\"))\nif len(matches) > 0 {\n\tfor _, m := range matches { os.Remove(m) } // clean stale sockets\n}","typeGuard":null,"tryCatchPattern":"err := limactl.Start(inst)\nif err != nil && strings.Contains(err.Error(), \"timed out waiting for external driver\") {\n\ttime.Sleep(2 * time.Second) // transient host slowness is the usual cause\n\treturn limactl.Start(inst)\n}\nreturn err","preventionTips":["Avoid starting VMs on heavily loaded hosts/CI runners","Clean stale lock and socket files from the instance dir after crashes","Keep driver plugins updated so socket-path conventions match lima","If timeouts recur, capture driver logs with --debug to find the hang"],"tags":["timeout","external-driver","socket","startup"],"backgroundTag":"driver-socket-wait-timeout","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}