{"record":{"id":"362a5de757b1daa0","repo":"lima-vm/lima","slug":"socket-must-be-specified-limactl-version-mismatch","errorCode":null,"errorMessage":"socket must be specified (limactl version mismatch?)","messagePattern":"socket must be specified \\(limactl version mismatch\\?\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/limactl/hostagent.go","lineNumber":64,"sourceCode":"\t\treturn err\n\t}\n\tif pidfile != \"\" {\n\t\tif existingPID, err := store.ReadPIDFile(pidfile); existingPID != 0 {\n\t\t\treturn fmt.Errorf(\"another hostagent may already be running with pid %d (pidfile %#q)\", existingPID, pidfile)\n\t\t} else if err != nil {\n\t\t\treturn fmt.Errorf(\"failed to determine if another hostagent is running: %w\", err)\n\t\t}\n\t\tif err := store.WritePIDFile(pidfile, os.Getpid()); err != nil {\n\t\t\treturn err\n\t\t}\n\t\tdefer os.RemoveAll(pidfile)\n\t}\n\tsocket, err := cmd.Flags().GetString(\"socket\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tif socket == \"\" {\n\t\treturn errors.New(\"socket must be specified (limactl version mismatch?)\")\n\t}\n\n\tinstName := args[0]\n\n\trunGUI, err := cmd.Flags().GetBool(\"run-gui\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tif runGUI {\n\t\t// Without this the call to vz.RunGUI fails. Adding it here, as this has to be called before the vz cgo loads.\n\t\truntime.LockOSThread()\n\t\tdefer runtime.UnlockOSThread()\n\t}\n\n\tsignalCh := make(chan os.Signal, 1)\n\tsignal.Notify(signalCh, os.Interrupt, syscall.SIGTERM)\n\n\tstdout := &syncWriter{w: cmd.OutOrStdout()}","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/cmd/limactl/hostagent.go#L46-L82","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\nlimactl hostagent myinstance\n// after\nlimactl start myinstance   # or: limactl hostagent --socket ~/.lima/myinstance/ga.sock myinstance","handlingStrategy":"validation","validationCode":"socket, _ := cmd.Flags().GetString(\"socket\")\nif socket == \"\" {\n    return errors.New(\"--socket is required for the internal hostagent command\")\n}","typeGuard":null,"tryCatchPattern":"if err := runHostagent(); err != nil {\n    if strings.Contains(err.Error(), \"socket must be specified\") { /* fix invocation: use limactl start */ }\n    return err\n}","preventionTips":["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"],"tags":["cli","socket","version-mismatch","lima"],"backgroundTag":"version-mismatch","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}