field `%s.guestPort` must match field `%s.guestPortRange[0]`

Error message

field `%s.guestPort` must match field `%s.guestPortRange[0]`

What it means

Same consistency rule as the guestPort/guestPortRange mismatch: when a specific `guestPort` is set on a portForward rule it must equal `guestPortRange[0]`. The error text names both fields with the rule index interpolated, e.g. `portForwards[2].guestPort must match portForwards[2].guestPortRange[0]`.

Source

Thrown at pkg/limayaml/validate.go:317

			errs = errors.Join(errs, fmt.Errorf("field `probe[%d].script` must start with a '#!' line", i))
		}
		switch p.Mode {
		case limatype.ProbeModeReadiness:
		default:
			errs = errors.Join(errs, fmt.Errorf("field `probe[%d].mode` can only be %#q", i, limatype.ProbeModeReadiness))
		}
	}
	for i, rule := range y.PortForwards {
		field := fmt.Sprintf("portForwards[%d]", i)
		if *rule.GuestIPMustBeZero && !rule.GuestIP.Equal(net.IPv4zero) {
			errs = errors.Join(errs, fmt.Errorf("field `%s.guestIPMustBeZero` can only be true when field `%s.guestIP` is 0.0.0.0", field, field))
		}
		if rule.GuestPort != 0 {
			if rule.GuestSocket != "" {
				errs = errors.Join(errs, fmt.Errorf("field `%s.guestPort` must be 0 when field `%s.guestSocket` is set", field, field))
			}
			if rule.GuestPort != rule.GuestPortRange[0] {
				errs = errors.Join(errs, fmt.Errorf("field `%s.guestPort` must match field `%s.guestPortRange[0]`", field, field))
			}
			// redundant validation to make sure the error contains the correct field name
			if err := validatePort(field+".guestPort", rule.GuestPort); err != nil {
				errs = errors.Join(errs, err)
			}
		}
		if rule.HostPort != 0 {
			if rule.HostSocket != "" {
				errs = errors.Join(errs, fmt.Errorf("field `%s.hostPort` must be 0 when field `%s.hostSocket` is set", field, field))
			}
			if rule.HostPort != rule.HostPortRange[0] {
				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)
			}
		}

View on GitHub (pinned to dd909d0973)

Solutions

Align guestPortRange[0] with guestPort (or drop guestPortRange)
Re-run the config through limactl's load/default pipeline so the fields are normalized
Remove guestPort entirely when forwarding a range via guestPortRange

Example fix

// before
portForwards:
- guestPort: 3000
  guestPortRange: [3001, 3005]
  hostPortRange: [3001, 3005]
// after
portForwards:
- guestPortRange: [3001, 3005]
  hostPortRange: [3001, 3005]

Defensive patterns

Strategy: validation

Validate before calling

for i, r := range cfg.PortForwards {
    if r.GuestPort != 0 && r.GuestPort != r.GuestPortRange[0] {
        return fmt.Errorf("portForwards[%d]: set either guestPort or guestPortRange, not mismatched both", i)
    }
}

Type guard

func portRangeConsistent(start, scalar int) bool {
    return scalar == 0 || scalar == start
}

Prevention

Use guestPortRange alone for range forwards, guestPort alone for single ports
Diff-check portForwards blocks after merges/rebases
Run limactl validate as a pre-commit hook on lima.yaml changes

When it happens

Trigger: Same as the scalar/range inconsistency: validating a config where rule.GuestPort != rule.GuestPortRange[0]; the dedicated message exists (see the redundant-validation comment in the source) so the field name is guaranteed to appear in the error.

Common situations: Hand-edited lima.yaml combining guestPort and guestPortRange with diverging values; Go code constructing rules without running limayaml defaulting; diff merges that updated one field only.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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