field `%s.hostSocket` can only be mapped from a single port

Error message

field `%s.hostSocket` can only be mapped from a single port or socket. not a range

What it means

A hostSocket endpoint can accept traffic from only a single guest endpoint. If the guest side is a port range spanning more than one port (guestSocket empty and guestPortRange width > 0), the mapping is ambiguous and rejected.

Source

Thrown at pkg/limayaml/validate.go:366

		}
		if rule.HostPortRange[0] > rule.HostPortRange[1] {
			errs = errors.Join(errs, fmt.Errorf("field `%s.hostPortRange[1]` must be greater than or equal to field `%s.hostPortRange[0]`", field, field))
		}
		if rule.GuestSocket != "" {
			if !path.IsAbs(rule.GuestSocket) {
				errs = errors.Join(errs, fmt.Errorf("field `%s.guestSocket` must be an absolute path, but is %#q", field, rule.GuestSocket))
			}
			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 == "" {

View on GitHub (pinned to dd909d0973)

Solutions

Collapse guestPortRange to a single port, e.g. [3000, 3000]
Or replace hostSocket with a hostPortRange of the same width
Create one rule per guest port, each with its own hostSocket

Example fix

// before
portForwards:
  - guestPortRange: [3000, 3010]
    hostSocket: /tmp/app.sock
// after
portForwards:
  - guestPortRange: [3000, 3000]
    hostSocket: /tmp/app.sock

Defensive patterns

Strategy: validation

Validate before calling

for i, rule := range y.PortForwards {
  if rule.HostSocket != "" && rule.GuestSocket == "" && rule.GuestPortRange[1]-rule.GuestPortRange[0] > 0 {
    return fmt.Errorf("portForwards[%d]: hostSocket needs a single guest port", i)
  }
}

Type guard

func singleGuestPort(rule limatype.PortForward) bool { return rule.GuestSocket != "" || rule.GuestPortRange[1]-rule.GuestPortRange[0] == 0 }

Try / catch

if err := limayaml.Validate(y, false); err != nil {
  if strings.Contains(err.Error(), "hostSocket` can only be mapped from a single port") {
    // narrow guestPortRange to a single port
  }
}

Prevention

When adding hostSocket, collapse guestPortRange to [n, n]
Map each guest port with its own rule if multiple ports are needed
Prefer hostPortRange over hostSocket for multi-port rules

When it happens

Trigger: Validate on a LimaYAML where portForwards[i].HostSocket != "", GuestSocket == "", and GuestPortRange[1]-GuestPortRange[0] > 0 (e.g. guestPortRange: [3000, 3010] with hostSocket set).

Common situations: Switching an existing multi-port rule to a host socket without shrinking guestPortRange; copying the hostSocket field into a range-based rule.

Related errors

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