{"record":{"id":"b737794dced72483","repo":"lima-vm/lima","slug":"field-s-guestport-must-be-0-when-field-s-gues","errorCode":null,"errorMessage":"field `%s.guestPort` must be 0 when field `%s.guestSocket` is set","messagePattern":"field `(.+?)\\.guestPort` must be 0 when field `(.+?)\\.guestSocket` is set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/limayaml/validate.go","lineNumber":314,"sourceCode":"\t\t\t}\n\t\t}\n\t\tif p.Script != nil && !strings.HasPrefix(*p.Script, \"#!\") {\n\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `probe[%d].script` must start with a '#!' line\", i))\n\t\t}\n\t\tswitch p.Mode {\n\t\tcase limatype.ProbeModeReadiness:\n\t\tdefault:\n\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `probe[%d].mode` can only be %#q\", i, limatype.ProbeModeReadiness))\n\t\t}\n\t}\n\tfor i, rule := range y.PortForwards {\n\t\tfield := fmt.Sprintf(\"portForwards[%d]\", i)\n\t\tif *rule.GuestIPMustBeZero && !rule.GuestIP.Equal(net.IPv4zero) {\n\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.guestIPMustBeZero` can only be true when field `%s.guestIP` is 0.0.0.0\", field, field))\n\t\t}\n\t\tif rule.GuestPort != 0 {\n\t\t\tif rule.GuestSocket != \"\" {\n\t\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.guestPort` must be 0 when field `%s.guestSocket` is set\", field, field))\n\t\t\t}\n\t\t\tif rule.GuestPort != rule.GuestPortRange[0] {\n\t\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.guestPort` must match field `%s.guestPortRange[0]`\", field, field))\n\t\t\t}\n\t\t\t// redundant validation to make sure the error contains the correct field name\n\t\t\tif err := validatePort(field+\".guestPort\", rule.GuestPort); err != nil {\n\t\t\t\terrs = errors.Join(errs, err)\n\t\t\t}\n\t\t}\n\t\tif rule.HostPort != 0 {\n\t\t\tif rule.HostSocket != \"\" {\n\t\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.hostPort` must be 0 when field `%s.hostSocket` is set\", field, field))\n\t\t\t}\n\t\t\tif rule.HostPort != rule.HostPortRange[0] {\n\t\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.hostPort` must match field `%s.hostPortRange[0]`\", field, field))\n\t\t\t}\n\t\t\t// redundant validation to make sure the error contains the correct field name\n\t\t\tif err := validatePort(field+\".hostPort\", rule.HostPort); err != nil {","sourceCodeStart":296,"sourceCodeEnd":332,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/limayaml/validate.go#L296-L332","documentation":"Port forward rules carry both a scalar `guestPort` and a `guestPortRange` [start,end]. When a specific guestPort is set, Validate() requires it to equal guestPortRange[0] so the two representations stay consistent. This is a redundancy check after limayaml defaulting/normalization, so it usually indicates hand-edited or programmatically inconsistent rules.","triggerScenarios":"Calling limactl validate/start/etc. with a portForwards rule where `guestPort: N` but `guestPortRange: [M, ...]` with M != N (typically after hand-editing or building the struct directly without defaulting).","commonSituations":"Manually writing guestPortRange alongside guestPort in lima.yaml; constructing PortForward structs in Go and filling one but not the other; version changes where the range field became part of the surface.","solutions":["Remove `guestPortRange` from the YAML and keep only `guestPort`","Or set `guestPortRange[0]` equal to the guestPort value","For a port range forward, omit the scalar guestPort and only use guestPortRange"],"exampleFix":"// before\nportForwards:\n- guestPort: 8080\n  guestPortRange: [8081, 8090]\n  hostPort: 8080\n// after\nportForwards:\n- guestPort: 8080\n  hostPort: 8080","handlingStrategy":"validation","validationCode":"for i, r := range cfg.PortForwards {\n    if r.GuestPort != 0 && r.GuestPort != r.GuestPortRange[0] {\n        return fmt.Errorf(\"portForwards[%d].guestPort must match guestPortRange[0]\", i)\n    }\n}","typeGuard":"func guestPortConsistent(r limatype.PortForward) bool {\n    return r.GuestPort == 0 || r.GuestPort == r.GuestPortRange[0]\n}","tryCatchPattern":null,"preventionTips":["In hand-written YAML, specify only guestPort (range fields are for defaults/normalization)","When constructing structs in Go, run limayaml Defaulting before Validate","Never edit guestPort and guestPortRange independently"],"tags":["config-validation","port-forward","lima-yaml"],"backgroundTag":"schema-validation-failed","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}