field `%s.guestIPMustBeZero` can only be true when field `%s

Error message

field `%s.guestIPMustBeZero` can only be true when field `%s.guestIP` is 0.0.0.0

What it means

The port forwarding rule sets guestIPMustBeZero=true, which forces the guest to bind 0.0.0.0, but guestIP is set to something other than 0.0.0.0 — the two settings contradict each other.

Source

Thrown at pkg/limayaml/validate.go:310

				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)
			}
		}
		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] {

View on GitHub (pinned to dd909d0973)

Solutions

Delete the `guestPort` field from the rule that sets `guestSocket`
Ensure the guest port is 0 (explicit `guestPort: 0`) if the schema requires the key
If both destinations are needed, create two separate portForward rules

Example fix

// before
portForwards:
- guestSocket: /run/docker.sock
  guestPort: 2375
  hostSocket: docker.sock
// after
portForwards:
- guestSocket: /run/docker.sock
  hostSocket: docker.sock

Defensive patterns

Strategy: validation

Validate before calling

for i, r := range cfg.PortForwards {
    if r.GuestSocket != "" && r.GuestPort != 0 {
        return fmt.Errorf("portForwards[%d]: guestPort must be 0 when guestSocket is set", i)
    }
}

Type guard

func socketForwardIsClean(r limatype.PortForward) bool {
    return r.GuestSocket == "" || r.GuestPort == 0
}

Prevention

When converting TCP forwards to socket forwards, delete guestPort/hostPort keys, don't just add socket keys
Keep one rule per destination; combine nothing
Validate after every YAML edit with limactl validate

When it happens

Trigger: Calling limactl validate/start/etc. with a portForwards rule that sets both `guestSocket: /path/to.sock` and a non-zero `guestPort`.

Common situations: Copy-pasting an existing TCP rule and adding guestSocket without removing guestPort; converting a TCP forward to a socket forward incrementally; defaults that left guestPort populated before socket was added.

Related errors

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