lima-vm/lima · error

failed to create driver client: %w

Error message

failed to create driver client: %w

What it means

After the external driver process starts and creates its socket, lima creates an RPC client over that socket via client.NewDriverClient. If the client cannot be established (socket disappeared, protocol/handshake mismatch), Start kills the driver process, waits for its exit, and returns this wrapped error. The driver binary itself launched fine, but lima cannot talk to it.

Source

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

	}()

	// Wait for the socket file to be created by the external driver.
	socketWaitCtx, socketWaitCancel := context.WithTimeout(ctx, 10*time.Second)
	defer socketWaitCancel()
	ticker := time.NewTicker(100 * time.Millisecond)
	defer ticker.Stop()
	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")
		}
	}
}

View on GitHub (pinned to dd909d0973)

Solutions

1. Re-run with --debug and check the driver's own stderr/logs for a crash message
2. Verify the external driver binary version is compatible with this lima release (upgrade the driver plugin)
3. Check the socket path length and that nothing deletes files in the instance dir
4. Retry starting the instance; a transient race may have removed the socket

Example fix

// before
$ limactl start myvm  # fails: failed to create driver client
// after: upgrade the external driver plugin to match limactl
$ limactl upgrade-drivers  # or reinstall the driver binary at the matching version
$ limactl start myvm

// pre-check: driver binary exists and is executable
if _, err := os.Stat(driverBinPath); err != nil {
	return fmt.Errorf("external driver binary missing: %w", err)
}

err := limactl.Start(inst)
if err != nil && strings.Contains(err.Error(), "failed to create driver client") {
	// usually version skew between limactl and the driver plugin
	// upgrade the driver plugin, then retry once
	return retryStart(inst)
}
return err

When it happens

Trigger: NewDriverClient(socketPath, ...) fails immediately after a successful process spawn — socket file removed between creation and dial, socket path too long for the OS, incompatible driver gRPC/API version, or the process crashed right after socket creation.

Common situations: Version mismatch between limactl and a third-party external driver plugin (old driver, new API); driver binary deleted its socket on early exit; very long LIMA_HOME paths exceeding unix socket path limits; antivirus deleting the socket.

Related errors

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

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