{"record":{"id":"2966641ad58f0f26","repo":"lima-vm/lima","slug":"field-s-hostport-must-be-0-when-field-s-hosts","errorCode":null,"errorMessage":"field `%s.hostPort` must be 0 when field `%s.hostSocket` is set","messagePattern":"field `(.+?)\\.hostPort` must be 0 when field `(.+?)\\.hostSocket` is set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/limayaml/validate.go","lineNumber":326,"sourceCode":"\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 {\n\t\t\t\terrs = errors.Join(errs, err)\n\t\t\t}\n\t\t}\n\t\tfor j := range 2 {\n\t\t\tif err := validatePort(fmt.Sprintf(\"%s.guestPortRange[%d]\", field, j), rule.GuestPortRange[j]); err != nil {\n\t\t\t\terrs = errors.Join(errs, err)\n\t\t\t}\n\t\t\tif rule.HostSocket == \"\" {\n\t\t\t\tif err := validatePort(fmt.Sprintf(\"%s.hostPortRange[%d]\", field, j), rule.HostPortRange[j]); err != nil {\n\t\t\t\t\terrs = errors.Join(errs, err)\n\t\t\t\t}\n\t\t\t}","sourceCodeStart":308,"sourceCodeEnd":344,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/limayaml/validate.go#L308-L344","documentation":"Lima's limayaml validator rejects a portForward rule that sets both a numeric hostPort and a hostSocket. A rule may forward to either a TCP/UDP port or a Unix socket on the host, never both at once. The conflict is detected inside Validate() while checking every entry of the portForwards array.","triggerScenarios":"Calling Validate (via limactl start/edit/restart, limactl template validate, limactl edit --yq, or templateArgs resolution) on a LimaYAML where some portForwards[i] has HostPort != 0 AND HostSocket != \"\".","commonSituations":"Hand-editing a portForward rule to switch from port to socket forwarding while leaving the old hostPort value in place; merging YAML fragments from two templates; scripted yq edits that set hostSocket without clearing hostPort.","solutions":["Remove the hostPort field from the rule, keeping hostSocket","Or remove hostSocket and keep hostPort (with a matching hostPortRange)","Run `limactl template validate` after editing to confirm the rule is now unambiguous"],"exampleFix":"// before\nportForwards:\n  - guestPort: 80\n    hostPort: 8080\n    hostSocket: /tmp/web.sock\n// after\nportForwards:\n  - guestPort: 80\n    hostSocket: /tmp/web.sock","handlingStrategy":"validation","validationCode":"for i, rule := range y.PortForwards {\n  if rule.HostPort != 0 && rule.HostSocket != \"\" {\n    return fmt.Errorf(\"portForwards[%d]: set either hostPort or hostSocket, not both\", i)\n  }\n}","typeGuard":"func ruleUsesPort(rule limatype.PortForward) bool { return rule.HostPort != 0 && rule.HostSocket == \"\" }","tryCatchPattern":"if err := limayaml.Validate(y, false); err != nil {\n  if strings.Contains(err.Error(), \"hostPort` must be 0 when\") {\n    // fix rule: drop hostPort where hostSocket is set\n  }\n}","preventionTips":["Choose one forwarding target (port or socket) per rule before editing","After yq/scripted edits, run `limactl template validate`","Keep hostSocket and hostPort in mutually exclusive template branches"],"tags":["lima","port-forwarding","config-validation"],"backgroundTag":"port-forward-config-conflict","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}