field `%s.hostSocket` must be less than UNIX_PATH_MAX=%d cha

Error message

field `%s.hostSocket` must be less than UNIX_PATH_MAX=%d characters, but is %d

What it means

Unix domain socket paths are limited to 104/108 bytes (UNIX_PATH_MAX, per osutil.UnixPathMax). A hostSocket longer than that cannot be bound by the hostagent forwarding listener, so validation fails early with the actual length reported.

Source

Thrown at pkg/limayaml/validate.go:373

			}
			if rule.HostSocket == "" && rule.HostPortRange[1]-rule.HostPortRange[0] > 0 {
				errs = errors.Join(errs, fmt.Errorf("field `%s.guestSocket` can only be mapped to a single port or socket. not a range", field))
			}
		}
		if rule.HostSocket != "" {
			if !filepath.IsAbs(rule.HostSocket) {
				// should be unreachable because FillDefault() will prepend the instance directory to relative names
				errs = errors.Join(errs, fmt.Errorf("field `%s.hostSocket` must be an absolute path, but is %#q", field, rule.HostSocket))
			}
			if rule.GuestSocket == "" && rule.GuestPortRange[1]-rule.GuestPortRange[0] > 0 {
				errs = errors.Join(errs, fmt.Errorf("field `%s.hostSocket` can only be mapped from a single port or socket. not a range", field))
			}
		} else if rule.GuestPortRange[1]-rule.GuestPortRange[0] != rule.HostPortRange[1]-rule.HostPortRange[0] {
			errs = errors.Join(errs, fmt.Errorf("field `%s.hostPortRange` must specify the same number of ports as field `%s.guestPortRange`", field, field))
		}

		if len(rule.HostSocket) >= osutil.UnixPathMax {
			errs = errors.Join(errs, fmt.Errorf("field `%s.hostSocket` must be less than UNIX_PATH_MAX=%d characters, but is %d",
				field, osutil.UnixPathMax, len(rule.HostSocket)))
		}
		switch rule.Proto {
		case limatype.ProtoTCP, limatype.ProtoUDP, limatype.ProtoAny:
		default:
			errs = errors.Join(errs, fmt.Errorf("field `%s.proto` must be %#q, %#q, or %#q", field, limatype.ProtoTCP, limatype.ProtoUDP, limatype.ProtoAny))
		}
		if rule.Reverse && rule.GuestSocket == "" {
			errs = errors.Join(errs, fmt.Errorf("field `%s.reverse` must be %t", field, false))
		}
		if rule.Reverse && rule.HostSocket == "" {
			errs = errors.Join(errs, fmt.Errorf("field `%s.reverse` must be %t", field, false))
		}
		// Not validating that the various GuestPortRanges and HostPortRanges are not overlapping. Rules will be
		// processed sequentially and the first matching rule for a guest port determines forwarding behavior.
	}
	for i, rule := range y.CopyToHost {
		field := fmt.Sprintf("CopyToHost[%d]", i)

View on GitHub (pinned to dd909d0973)

Solutions

Shorten the hostSocket path, e.g. place the socket in /tmp with a short name
Shorten the instance name or LIMA_HOME directory so the derived socket path fits
Use a symlink-free short parent directory for the socket

Example fix

// before
portForwards:
  - guestPort: 80
    hostSocket: /Users/averylongusername/Library/Application Support/lima/very-long-instance-name/sock
// after
portForwards:
  - guestPort: 80
    hostSocket: /tmp/lv80.sock

Defensive patterns

Strategy: validation

Validate before calling

import "github.com/lima-vm/lima/v2/pkg/osutil"

for i, rule := range y.PortForwards {
  if len(rule.HostSocket) >= osutil.UnixPathMax {
    return fmt.Errorf("portForwards[%d]: hostSocket too long (%d >= %d)", i, len(rule.HostSocket), osutil.UnixPathMax)
  }
}

Type guard

func socketPathFits(p string) bool { return p == "" || len(p) < osutil.UnixPathMax }

Try / catch

if err := limayaml.Validate(y, false); err != nil {
  if strings.Contains(err.Error(), "UNIX_PATH_MAX") {
    // shorten hostSocket or move it to a short directory like /tmp
  }
}

Prevention

Keep instance names and LIMA_HOME short
Place host sockets in short directories like /tmp
Check path length when templates compute socket paths from instance dirs

When it happens

Trigger: Validate on a LimaYAML where len(portForwards[i].HostSocket) >= osutil.UnixPathMax — typically deep instance directories like ~/.lima/very-long-instance-name/vz/... plus a long socket name.

Common situations: Long LIMA_HOME paths on macOS/Linux; long instance names compounded with subdirectory paths; nested container runtimes placing sockets under very long prefixes.

Related errors

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