field `%s.hostPortRange` must specify the same number of por

Error message

field `%s.hostPortRange` must specify the same number of ports as field `%s.guestPortRange`

What it means

When neither side uses sockets, the guest and host port ranges must have the same width: Lima forwards ports one-to-one, so a range of N guest ports needs exactly N host ports. This is checked only in the else branch, i.e. when HostSocket is empty.

Source

Thrown at pkg/limayaml/validate.go:369

		}
		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 == "" {
			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

View on GitHub (pinned to dd909d0973)

Solutions

Make both ranges the same length
Or remove hostPortRange so Lima auto-assigns host ports for the guest range
Or split into multiple single-port rules

Example fix

// before
portForwards:
  - guestPortRange: [8080, 8082]
    hostPortRange: [9080, 9081]
// after
portForwards:
  - guestPortRange: [8080, 8082]
    hostPortRange: [9080, 9082]

Defensive patterns

Strategy: validation

Validate before calling

for i, rule := range y.PortForwards {
  if rule.HostSocket == "" && rule.GuestPortRange[1]-rule.GuestPortRange[0] != rule.HostPortRange[1]-rule.HostPortRange[0] {
    return fmt.Errorf("portForwards[%d]: guest and host ranges must have equal width", i)
  }
}

Type guard

func rangeWidthsMatch(rule limatype.PortForward) bool { return rule.GuestPortRange[1]-rule.GuestPortRange[0] == rule.HostPortRange[1]-rule.HostPortRange[0] }

Try / catch

if err := limayaml.Validate(y, false); err != nil {
  if strings.Contains(err.Error(), "must specify the same number of ports") {
    // resize hostPortRange (or drop it for auto-assignment)
  }
}

Prevention

Edit guest and host ranges together
Omit hostPortRange to let Lima auto-assign host ports for guest ranges
Add a config lint step that checks range widths

When it happens

Trigger: Validate on a LimaYAML where portForwards[i] has no hostSocket but GuestPortRange[1]-GuestPortRange[0] != HostPortRange[1]-HostPortRange[0], e.g. guestPortRange: [8080,8082] with hostPortRange: [9080,9081].

Common situations: Editing one range but not the other; adding a port to the guest range expecting Lima to pick free host ports automatically (Lima does not for explicit ranges); merge conflicts resolved on one side only.

Related errors

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