lima-vm/lima · error

timed out waiting for external driver to create socket file

Error message

timed out waiting for external driver to create socket file

What it means

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.

Source

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

						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)
	for _, pidFile := range files {
		pidData, err := os.ReadFile(pidFile)
		if err != nil {
			_ = os.Remove(pidFile)
			continue
		}

View on GitHub (pinned to dd909d0973)

Solutions

1. Retry the start; transient slowness is the most common cause
2. Capture driver logs with debug enabled to find where initialization hangs
3. Remove stale state in the instance dir (locks, old sockets) and retry
4. Upgrade or replace the driver plugin so its socket path matches what lima expects

Example fix

// before: stale lock makes driver hang past timeout
$ limactl start myvm  # timed out waiting for external driver to create socket file
// after
$ rm -f ~/.lima/myvm/*.lock ~/.lima/myvm/*.sock
$ limactl start myvm

// pre-check: no stale sockets/locks in the instance dir
matches, _ := filepath.Glob(filepath.Join(instanceDir, "*.sock"))
if len(matches) > 0 {
	for _, m := range matches { os.Remove(m) } // clean stale sockets
}

err := limactl.Start(inst)
if err != nil && strings.Contains(err.Error(), "timed out waiting for external driver") {
	time.Sleep(2 * time.Second) // transient host slowness is the usual cause
	return limactl.Start(inst)
}
return err

When it happens

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

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

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• external driver process exited before creating socket file
• external driver process exited before creating 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/a844a70de3fbf4ee. Report an issue: GitHub.