lima-vm/lima · error

external driver process exited before creating socket file

Error message

external driver process exited before creating socket file

What it means

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.

Source

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

	for {
		select {
		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)

View on GitHub (pinned to dd909d0973)

Solutions

1. Run the driver binary manually with the same args to see its output (it likely prints usage or a quiet exit reason)
2. Verify the external driver name maps to the correct executable in the driver registry/PATH
3. Rebuild/reinstall the driver plugin matching your lima version
4. Enable debug logging to capture the driver's stdout/stderr during startup

// sanity: the driver binary responds to --help with exit 0 and expected output
out, err := exec.Command(driverBinPath, "--help").CombinedOutput()
if err != nil || !strings.Contains(string(out), expectedUsageMarker) {
	return fmt.Errorf("driver binary %s does not behave as expected", driverBinPath)
}

if err := limactl.Start(inst); err != nil {
	if strings.Contains(err.Error(), "exited before creating socket file") {
		// driver exits cleanly but silently: wrong/incompatible binary
		// reinstall the matching driver plugin and fall back to a supported driver
	}
	return err
}

When it happens

Trigger: 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.

Common situations: 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.

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
• inspect status command failed: %w; stderr: %s

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