lima-vm/lima · error

field `probe[%d].mode` can only be %#q

Error message

field `probe[%d].mode` can only be %#q

What it means

`guestIPMustBeZero` is a marker meaning 'the guest IP must be 0.0.0.0 (any interface)'. Validate() enforces consistency: it can only be true when the rule's guestIP actually equals 0.0.0.0. Note this check runs on the post-default config where guestIP must have been explicitly set to 0.0.0.0 for this combination to be legal.

Source

Thrown at pkg/limayaml/validate.go:304

			}
		}
	}
	for i, p := range y.Probes {
		if p.File != nil {
			if p.File.URL != "" {
				errs = errors.Join(errs, fmt.Errorf("field `probe[%d].file.url` must be empty during validation (script should already be embedded)", i))
			}
			if p.File.Digest != nil {
				errs = errors.Join(errs, fmt.Errorf("field `probe[%d].file.digest` support is not yet implemented", i))
			}
		}
		if p.Script != nil && !strings.HasPrefix(*p.Script, "#!") {
			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)
			}

View on GitHub (pinned to dd909d0973)

Solutions

  1. Remove `guestIPMustBeZero: true`, or set it to false, when guestIP is a specific address
  2. Set `guestIP: 0.0.0.0` if binding all guest interfaces is intended
  3. Rely on limayaml defaulting (guestIPMustBeZero is normally computed, not hand-set) and only override guestIP

Example fix

// before
portForwards:
- guestIP: 127.0.0.1
  guestIPMustBeZero: true
  guestPort: 8080
  hostPort: 8080
// after
portForwards:
- guestIP: 127.0.0.1
  guestPort: 8080
  hostPort: 8080
Defensive patterns

Strategy: validation

Validate before calling

for i, r := range cfg.PortForwards {
    if r.GuestIPMustBeZero && !r.GuestIP.Equal(net.IPv4zero) {
        return fmt.Errorf("portForwards[%d]: guestIPMustBeZero requires guestIP 0.0.0.0", i)
    }
}

Type guard

func guestIPMustBeZeroConsistent(r limatype.PortForward) bool {
    return !r.GuestIPMustBeZero || r.GuestIP.Equal(net.IPv4zero)
}

Prevention

When it happens

Trigger: Calling limactl validate/start/etc. with a portForward rule where `guestIPMustBeZero: true` (either hand-written or set programmatically) while `guestIP` is a concrete address such as 127.0.0.1 or 192.168.5.15.

Common situations: Setting guestIP to a specific IP and separately toggling guestIPMustBeZero without understanding it is derived; templates or tools that set the flag but leave a stale guestIP; after editing rules from another rule that had 0.0.0.0.

Related errors

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