field `%s.hostPortRange[1]` must be greater than or equal to

Error message

field `%s.hostPortRange[1]` must be greater than or equal to field `%s.hostPortRange[0]`

What it means

The host port range is inverted: hostPortRange[1] (end) is smaller than hostPortRange[0] (start), so no valid port interval can be forwarded.

Source

Thrown at pkg/limayaml/validate.go:350

			if err := validatePort(field+".hostPort", rule.HostPort); err != nil {
				errs = errors.Join(errs, err)
			}
		}
		for j := range 2 {
			if err := validatePort(fmt.Sprintf("%s.guestPortRange[%d]", field, j), rule.GuestPortRange[j]); err != nil {
				errs = errors.Join(errs, err)
			}
			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] {

View on GitHub (pinned to dd909d0973)

Solutions

Swap the values so hostPortRange[0] <= hostPortRange[1]
Use a single-element range [n, n] if only one port is needed

Example fix

// before
portForwards:
  - guestPortRange: [8080, 8081]
    hostPortRange: [8081, 8080]
// after
portForwards:
  - guestPortRange: [8080, 8081]
    hostPortRange: [8080, 8081]

Defensive patterns

Strategy: validation

Validate before calling

for i, rule := range y.PortForwards {
  if rule.HostSocket == "" && rule.HostPortRange[0] > rule.HostPortRange[1] {
    return fmt.Errorf("portForwards[%d]: hostPortRange is inverted", i)
  }
}

Type guard

func hostRangeOrdered(r [2]int) bool { return r[0] <= r[1] }

Try / catch

if err := limayaml.Validate(y, false); err != nil {
  if strings.Contains(err.Error(), "hostPortRange[1]` must be greater") {
    // swap hostPortRange elements
  }
}

Prevention

Write ranges as [low, high] consistently for guest and host
Compute ranges with min/max helpers in generators
Validate configs before `limactl start`

When it happens

Trigger: Validate on a LimaYAML where portForwards[i].HostPortRange[0] > HostPortRange[1] and HostSocket == "" — e.g. hostPortRange: [9000, 8080].

Common situations: Typo in a manually written range; assuming [end, start] ordering; template generation code that computes hi/lo in the wrong order.

Related errors

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