field `%s.guestSocket` can only be mapped to a single port o

Error message

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

What it means

A guestSocket target is a single host endpoint. If the host side is a port range (hostSocket empty and hostPortRange spans more than one port), Lima cannot decide which host port the single guest socket maps to, so validation fails.

Source

Thrown at pkg/limayaml/validate.go:357

			}
			if rule.HostSocket == "" {
				if err := validatePort(fmt.Sprintf("%s.hostPortRange[%d]", field, j), rule.HostPortRange[j]); err != nil {
					errs = errors.Join(errs, err)
				}
			}
		}
		if rule.GuestPortRange[0] > rule.GuestPortRange[1] {
			errs = errors.Join(errs, fmt.Errorf("field `%s.guestPortRange[1]` must be greater than or equal to field `%s.guestPortRange[0]`", field, field))
		}
		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)))
		}

View on GitHub (pinned to dd909d0973)

Solutions

Collapse hostPortRange to a single port, e.g. [8080, 8080]
Or add a matching hostSocket instead of a host port range
Split into multiple rules, one per host port

Example fix

// before
portForwards:
  - guestSocket: /tmp/app.sock
    hostPortRange: [8080, 8085]
// after
portForwards:
  - guestSocket: /tmp/app.sock
    hostPortRange: [8080, 8080]

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

func singleHostPort(rule limatype.PortForward) bool { return rule.HostSocket != "" || rule.HostPortRange[1]-rule.HostPortRange[0] == 0 }

Try / catch

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

Prevention

When adding guestSocket, collapse hostPortRange to [n, n]
Use hostSocket instead of a host port range for socket targets
Keep socket rules separate from range rules

When it happens

Trigger: Validate on a LimaYAML where portForwards[i].GuestSocket != "", HostSocket == "", and HostPortRange[1]-HostPortRange[0] > 0 (e.g. hostPortRange: [8080, 8085] with guestSocket set).

Common situations: Adding guestSocket to an existing multi-port forwarding rule without narrowing hostPortRange; converting a range rule to socket forwarding by only adding the socket field.

Related errors

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