{"record":{"id":"9c3c6d56928fae54","repo":"lima-vm/lima","slug":"socket-path-q-is-too-long-unix-path-max-d","errorCode":null,"errorMessage":"socket path %#q is too long: >= UNIX_PATH_MAX=%d","messagePattern":"socket path %#q is too long: >= UNIX_PATH_MAX=(.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/sshutil/sshutil.go","lineNumber":579,"sourceCode":"// is treated as a no-op (returns false). This lets callers recover from a wedged\n// session without clobbering a healthy ControlMaster.\nfunc RemoveStaleControlMaster(ctx context.Context, instDir string) (bool, error) {\n\tif IsControlMasterRunning(ctx, instDir) {\n\t\treturn false, nil\n\t}\n\texisted := IsControlMasterExisting(instDir)\n\tcontrolSock := filepath.Join(instDir, filenames.SSHSock)\n\tif err := os.RemoveAll(controlSock); err != nil {\n\t\treturn false, err\n\t}\n\treturn existed, nil\n}\n\n// SSHOpts adds the following options to CommonOptions: User, ControlMaster, ControlPath, ControlPersist.\nfunc SSHOpts(ctx context.Context, sshExe SSHExe, instDir, username string, useDotSSH, forwardAgent, forwardX11, forwardX11Trusted bool) ([]string, error) {\n\tcontrolSock := filepath.Join(instDir, filenames.SSHSock)\n\tif len(controlSock) >= osutil.UnixPathMax {\n\t\treturn nil, fmt.Errorf(\"socket path %#q is too long: >= UNIX_PATH_MAX=%d\", controlSock, osutil.UnixPathMax)\n\t}\n\topts, err := CommonOpts(ctx, sshExe, useDotSSH)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tcontrolPath := fmt.Sprintf(`ControlPath=\"%s\"`, controlSock)\n\tif runtime.GOOS == \"windows\" {\n\t\tcontrolSock, err = PathForSSH(ctx, sshExe, controlSock)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tcontrolPath = fmt.Sprintf(`ControlPath='%s'`, controlSock)\n\t}\n\topts = append(opts,\n\t\tfmt.Sprintf(\"User=%s\", username), // guest and host have the same username, but we should specify the username explicitly (#85)\n\t\t\"ControlMaster=auto\",\n\t\tcontrolPath,\n\t\t\"ControlPersist=yes\",","sourceCodeStart":561,"sourceCodeEnd":597,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/sshutil/sshutil.go#L561-L597","documentation":"SSHOpts builds a ControlPath socket under the instance directory; UNIX domain socket paths are limited to ~104 characters (UNIX_PATH_MAX). If the full control socket path exceeds that limit, ssh -o ControlPath would silently fail to bind, so Lima validates the length upfront and errors out.","triggerScenarios":"Calling SSHOpts (or anything using it: limactl shell, limactl show-ssh, tunnel, Command, instance start) when filepath.Join(instDir, filenames.SSHSock) length >= osutil.UnixPathMax — typically because LIMA_HOME or the instance directory is deep/long.","commonSituations":"LIMA_HOME set to a long custom path (e.g. nested project dirs, long Windows user profile paths); long instance names pushing the path over the limit; network home directories with long prefixes.","solutions":["Move LIMA_HOME to a shorter path, e.g. export LIMA_HOME=~/l or another shallow directory.","Shorten the instance name and recreate the instance.","On macOS, relocate the home to a path under /Users or use a symlink-safe short root (note the symlink itself does not shorten the resolved path — the physical path must be short)."],"exampleFix":"// before\nexport LIMA_HOME=/Users/verylongname/Library/Application Support/containers/lima\nlimactl start my-instance-with-a-very-long-name\n// after\nexport LIMA_HOME=~/l\nlimactl start myinst","handlingStrategy":"validation","validationCode":"controlSock := filepath.Join(instDir, \"ssh.sock\")\nif len(controlSock) >= 104 {\n    return fmt.Errorf(\"instance dir too long (%d chars): move LIMA_HOME to a shorter path\", len(controlSock))\n}","typeGuard":null,"tryCatchPattern":"opts, err := sshutil.SSHOpts(ctx, sshExe, instDir, user, useDotSSH, fa, fx, fxt)\nif err != nil {\n    if strings.Contains(err.Error(), \"too long\") {\n        // relocate LIMA_HOME / shorten instance name\n    }\n    return err\n}","preventionTips":["Keep LIMA_HOME a short path (e.g. ~/.lima)","Use short instance names","On Windows watch for long profile paths; consider short roots like C:\\l"],"tags":["unix-socket","path-length","ssh"],"backgroundTag":"socket-path-too-long","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}