socket must be specified (limactl version mismatch?)

Error message

socket must be specified (limactl version mismatch?)

What it means

The internal `limactl hostagent` subcommand requires a --socket flag telling it which UNIX socket to serve on. An empty value means the caller (usually the limactl parent process) did not pass it, which in practice indicates the limactl binary and its hostagent invocation are from mismatched versions.

Source

Thrown at cmd/limactl/hostagent.go:64

		return err
	}
	if pidfile != "" {
		if existingPID, err := store.ReadPIDFile(pidfile); existingPID != 0 {
			return fmt.Errorf("another hostagent may already be running with pid %d (pidfile %#q)", existingPID, pidfile)
		} else if err != nil {
			return fmt.Errorf("failed to determine if another hostagent is running: %w", err)
		}
		if err := store.WritePIDFile(pidfile, os.Getpid()); err != nil {
			return err
		}
		defer os.RemoveAll(pidfile)
	}
	socket, err := cmd.Flags().GetString("socket")
	if err != nil {
		return err
	}
	if socket == "" {
		return errors.New("socket must be specified (limactl version mismatch?)")
	}

	instName := args[0]

	runGUI, err := cmd.Flags().GetBool("run-gui")
	if err != nil {
		return err
	}
	if runGUI {
		// Without this the call to vz.RunGUI fails. Adding it here, as this has to be called before the vz cgo loads.
		runtime.LockOSThread()
		defer runtime.UnlockOSThread()
	}

	signalCh := make(chan os.Signal, 1)
	signal.Notify(signalCh, os.Interrupt, syscall.SIGTERM)

	stdout := &syncWriter{w: cmd.OutOrStdout()}

View on GitHub (pinned to dd909d0973)

Solutions

Do not call `limactl hostagent` directly — use `limactl start <instance>`, which supplies the socket
If scripting, pass --socket explicitly: `limactl hostagent --socket /path/to/sock ...`
Ensure a single limactl version is installed (`which -a limactl`) and remove stale wrappers/aliases

Example fix

// before
limactl hostagent myinstance
// after
limactl start myinstance   # or: limactl hostagent --socket ~/.lima/myinstance/ga.sock myinstance

Defensive patterns

Strategy: validation

Validate before calling

socket, _ := cmd.Flags().GetString("socket")
if socket == "" {
    return errors.New("--socket is required for the internal hostagent command")
}

Try / catch

if err := runHostagent(); err != nil {
    if strings.Contains(err.Error(), "socket must be specified") { /* fix invocation: use limactl start */ }
    return err
}

Prevention

Use `limactl start` instead of invoking the internal hostagent command
Pass --socket explicitly when scripting the internal command
Ensure only one limactl version is on PATH

When it happens

Trigger: Invoking `limactl hostagent` manually without --socket, or a start flow where the socket flag was not forwarded; mixing limactl binaries of different versions (e.g. an old wrapper script calling a newer installed limactl).

Common situations: Hand-editing or scripting the internal hostagent command; upgrading lima while an alias/wrapper still points at an older binary; copy-pasted commands from docs of a different version.

Related errors

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