{"record":{"id":"07bb5843dc760812","repo":"lima-vm/lima","slug":"external-driver-process-exited-before-creating-soc","errorCode":null,"errorMessage":"external driver process exited before creating socket file","messagePattern":"external driver process exited before creating socket file","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/driver/external/server/server.go","lineNumber":262,"sourceCode":"\tfor {\n\t\tselect {\n\t\tcase <-ticker.C:\n\t\t\tif _, err := os.Stat(socketPath); err == nil && isServerRunning(socketPath) {\n\t\t\t\tdriverLogger.Debugf(\"Detected socket file at %s\", socketPath)\n\t\t\t\textDriver.Client, err = client.NewDriverClient(socketPath, extDriver.Logger)\n\t\t\t\tif err != nil {\n\t\t\t\t\tif err := cmd.Process.Kill(); err != nil {\n\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)","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/driver/external/server/server.go#L244-L280","documentation":"lima waits on a channel for the external driver process to create its socket file. If the process exits first, Start selects the procExit case and, when the exit status is clean (nil), returns this plain error — the driver terminated itself without ever publishing a socket and without reporting a failure code. It means the driver binary ran and died quietly.","triggerScenarios":"The spawned external driver process exits with status 0 before creating the expected socket file in the instance directory — e.g. the binary misparses its arguments, prints usage and exits 0, or has an early-return code path on unsupported platform.","commonSituations":"Wrong binary installed at the driver path (a wrapper script that exits 0); driver built for a different lima driver-API version that exits gracefully on unknown requests; misconfigured driver name mapping to an incompatible executable.","solutions":["Run the driver binary manually with the same args to see its output (it likely prints usage or a quiet exit reason)","Verify the external driver name maps to the correct executable in the driver registry/PATH","Rebuild/reinstall the driver plugin matching your lima version","Enable debug logging to capture the driver's stdout/stderr during startup"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// sanity: the driver binary responds to --help with exit 0 and expected output\nout, err := exec.Command(driverBinPath, \"--help\").CombinedOutput()\nif err != nil || !strings.Contains(string(out), expectedUsageMarker) {\n\treturn fmt.Errorf(\"driver binary %s does not behave as expected\", driverBinPath)\n}","typeGuard":null,"tryCatchPattern":"if err := limactl.Start(inst); err != nil {\n\tif strings.Contains(err.Error(), \"exited before creating socket file\") {\n\t\t// driver exits cleanly but silently: wrong/incompatible binary\n\t\t// reinstall the matching driver plugin and fall back to a supported driver\n\t}\n\treturn err\n}","preventionTips":["Verify the driver path points at the real plugin binary, not a wrapper that exits 0","Rebuild plugins against the lima driver-API version you run","Enable --debug to capture the driver's silent output before it exits","Test new driver plugins in isolation before pointing instances at them"],"tags":["external-driver","process-exit","socket","startup"],"backgroundTag":"driver-exited-before-socket-ready","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}