field `%s.guestPortRange[1]` must be greater than or equal t

Error message

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

What it means

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

Source

Thrown at pkg/limayaml/validate.go:347

				errs = errors.Join(errs, fmt.Errorf("field `%s.hostPort` must match field `%s.hostPortRange[0]`", field, field))
			}
			// redundant validation to make sure the error contains the correct field name
			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 {

View on GitHub (pinned to dd909d0973)

Solutions

Swap the two values so guestPortRange[0] <= guestPortRange[1]
If a single port was intended, set the range to [n, n]

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Always write ranges as [low, high]
Use single-port [n, n] ranges when no range is intended
Lint the config with `limactl template validate` in CI

When it happens

Trigger: Validate on a LimaYAML where portForwards[i].GuestPortRange[0] > GuestPortRange[1], e.g. guestPortRange: [9090, 8080].

Common situations: Typo when typing the range by hand; assuming the range syntax is [end, start]; scripted edits that swap the array elements.

Related errors

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