What causes "socket path %#q is too long: >= UNIX_PATH_MAX=%d" in lima-vm/lima?

Move LIMA_HOME to a shorter path, e.g. export LIMA_HOME=~/l or another shallow directory.

socket path %#q is too long: >= UNIX_PATH_MAX=%d

Error message

socket path %#q is too long: >= UNIX_PATH_MAX=%d

What it means

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.

Source

Thrown at pkg/sshutil/sshutil.go:579

// is treated as a no-op (returns false). This lets callers recover from a wedged
// session without clobbering a healthy ControlMaster.
func RemoveStaleControlMaster(ctx context.Context, instDir string) (bool, error) {
	if IsControlMasterRunning(ctx, instDir) {
		return false, nil
	}
	existed := IsControlMasterExisting(instDir)
	controlSock := filepath.Join(instDir, filenames.SSHSock)
	if err := os.RemoveAll(controlSock); err != nil {
		return false, err
	}
	return existed, nil
}

// SSHOpts adds the following options to CommonOptions: User, ControlMaster, ControlPath, ControlPersist.
func SSHOpts(ctx context.Context, sshExe SSHExe, instDir, username string, useDotSSH, forwardAgent, forwardX11, forwardX11Trusted bool) ([]string, error) {
	controlSock := filepath.Join(instDir, filenames.SSHSock)
	if len(controlSock) >= osutil.UnixPathMax {
		return nil, fmt.Errorf("socket path %#q is too long: >= UNIX_PATH_MAX=%d", controlSock, osutil.UnixPathMax)
	}
	opts, err := CommonOpts(ctx, sshExe, useDotSSH)
	if err != nil {
		return nil, err
	}
	controlPath := fmt.Sprintf(`ControlPath="%s"`, controlSock)
	if runtime.GOOS == "windows" {
		controlSock, err = PathForSSH(ctx, sshExe, controlSock)
		if err != nil {
			return nil, err
		}
		controlPath = fmt.Sprintf(`ControlPath='%s'`, controlSock)
	}
	opts = append(opts,
		fmt.Sprintf("User=%s", username), // guest and host have the same username, but we should specify the username explicitly (#85)
		"ControlMaster=auto",
		controlPath,
		"ControlPersist=yes",

View on GitHub (pinned to dd909d0973)

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).

Example fix

// before
export LIMA_HOME=/Users/verylongname/Library/Application Support/containers/lima
limactl start my-instance-with-a-very-long-name
// after
export LIMA_HOME=~/l
limactl start myinst

Defensive patterns

Strategy: validation

Validate before calling

controlSock := filepath.Join(instDir, "ssh.sock")
if len(controlSock) >= 104 {
    return fmt.Errorf("instance dir too long (%d chars): move LIMA_HOME to a shorter path", len(controlSock))
}

Try / catch

opts, err := sshutil.SSHOpts(ctx, sshExe, instDir, user, useDotSSH, fa, fx, fxt)
if err != nil {
    if strings.Contains(err.Error(), "too long") {
        // relocate LIMA_HOME / shorten instance name
    }
    return err
}

Prevention

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

When it happens

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

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

Related errors

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