lima-vm/lima · error

external driver process exited before creating socket file:

Error message

external driver process exited before creating socket file: %w

What it means

Same wait-for-socket loop as above, but here the driver process exited with a non-nil waitErr (non-zero exit status or signal), so the error wraps that status: 'external driver process exited before creating socket file: <waitErr>'. The wrapped exit error is the real diagnostic — it usually carries the driver's exit code or the signal that killed it.

Source

Thrown at pkg/driver/external/server/server.go:264

		case <-ticker.C:
			if _, err := os.Stat(socketPath); err == nil && isServerRunning(socketPath) {
				driverLogger.Debugf("Detected socket file at %s", socketPath)
				extDriver.Client, err = client.NewDriverClient(socketPath, extDriver.Logger)
				if err != nil {
					if err := cmd.Process.Kill(); err != nil {
						driverLogger.Errorf("Failed to kill external driver process after client creation failure: %v", err)
					}
					<-procExit
					return fmt.Errorf("failed to create driver client: %w", err)
				}
				driverLogger.Debugf("External driver %s started successfully", extDriver.Name)
				return nil
			}
		case waitErr := <-procExit:
			if waitErr == nil {
				return errors.New("external driver process exited before creating socket file")
			}
			return fmt.Errorf("external driver process exited before creating socket file: %w", waitErr)
		case <-socketWaitCtx.Done():
			if err := cmd.Process.Kill(); err != nil {
				driverLogger.Errorf("Failed to kill external driver process after socket wait timeout: %v", err)
			}
			<-procExit
			return errors.New("timed out waiting for external driver to create socket file")
		}
	}
}

// Stop finds and stops any external driver server processes in the given
// instance directory using PID files. If force is true, SIGKILL is sent;
// otherwise SIGTERM is sent and we wait for the process to exit.
// Also cleans up PID files and socket files.
func Stop(instDir string, force bool) {
	logrus.Debugf("Stopping external driver server in instance directory %s", instDir)
	pidPattern := filepath.Join(instDir, "*.drv.pid")
	files, _ := filepath.Glob(pidPattern)

View on GitHub (pinned to dd909d0973)

Solutions

1. Read the wrapped exit code in the error and the driver's captured stderr to identify the crash cause
2. Run the driver binary directly to reproduce (e.g. missing .so -> install dependencies)
3. Re-download/rebuild the driver plugin for the correct platform
4. Check dmesg/journal for OOM or segfault reports at the failure time

Example fix

// before: binary for wrong arch exits with 'exec format error'
external driver process exited before creating socket file: exit status 126
// after: install the correct platform build
$ file ~/.lima/drivers/mydriver/mydriver  # check arch
$ limactl reinstall-driver mydriver --arch=$(uname -m)

// pre-check binary runs on this platform
if runtime.GOOS != expectedDriverGOOS || runtime.GOARCH != expectedDriverGOARCH {
	return fmt.Errorf("driver plugin built for wrong platform")
}

if err := limactl.Start(inst); err != nil {
	var exitErr *exec.ExitError
	if errors.As(err, &exitErr) {
		log.Printf("driver crashed: code=%d", exitErr.ExitCode())
		// reinstall plugin / check dmesg for OOM, then retry
	}
	return err
}

When it happens

Trigger: The external driver binary crashes or is killed (non-zero exit/signal) before writing its socket — missing shared libraries, panic in the driver, exec format error, OOM kill, or the binary doesn't exist and cmd.Start failed differently than expected.

Common situations: Driver binary compiled for the wrong OS/arch; driver panics on an unsupported config field; system OOM killer terminates it; missing dynamic dependencies (e.g. missing libvirt/gvproxy-adjacent libs); corrupted download of the plugin.

Related errors

• external driver process exited before creating socket file
• timed out waiting for external driver to create socket file
• failed to write driver PID file: %w
• failed to create driver client: %w
• socket must be specified (limactl version mismatch?)

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/5b6d58e9e8f11a6d. Report an issue: GitHub.