{"record":{"id":"83f645e937456b51","repo":"lima-vm/lima","slug":"field-s-guestsocket-can-only-be-mapped-to-a-sin","errorCode":null,"errorMessage":"field `%s.guestSocket` can only be mapped to a single port or socket. not a range","messagePattern":"field `(.+?)\\.guestSocket` can only be mapped to a single port or socket\\. not a range","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/limayaml/validate.go","lineNumber":357,"sourceCode":"\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}\n\t\t}\n\t\tif rule.GuestPortRange[0] > rule.GuestPortRange[1] {\n\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.guestPortRange[1]` must be greater than or equal to field `%s.guestPortRange[0]`\", field, field))\n\t\t}\n\t\tif rule.HostPortRange[0] > rule.HostPortRange[1] {\n\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.hostPortRange[1]` must be greater than or equal to field `%s.hostPortRange[0]`\", field, field))\n\t\t}\n\t\tif rule.GuestSocket != \"\" {\n\t\t\tif !path.IsAbs(rule.GuestSocket) {\n\t\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.guestSocket` must be an absolute path, but is %#q\", field, rule.GuestSocket))\n\t\t\t}\n\t\t\tif rule.HostSocket == \"\" && rule.HostPortRange[1]-rule.HostPortRange[0] > 0 {\n\t\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.guestSocket` can only be mapped to a single port or socket. not a range\", field))\n\t\t\t}\n\t\t}\n\t\tif rule.HostSocket != \"\" {\n\t\t\tif !filepath.IsAbs(rule.HostSocket) {\n\t\t\t\t// should be unreachable because FillDefault() will prepend the instance directory to relative names\n\t\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.hostSocket` must be an absolute path, but is %#q\", field, rule.HostSocket))\n\t\t\t}\n\t\t\tif rule.GuestSocket == \"\" && rule.GuestPortRange[1]-rule.GuestPortRange[0] > 0 {\n\t\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.hostSocket` can only be mapped from a single port or socket. not a range\", field))\n\t\t\t}\n\t\t} else if rule.GuestPortRange[1]-rule.GuestPortRange[0] != rule.HostPortRange[1]-rule.HostPortRange[0] {\n\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.hostPortRange` must specify the same number of ports as field `%s.guestPortRange`\", field, field))\n\t\t}\n\n\t\tif len(rule.HostSocket) >= osutil.UnixPathMax {\n\t\t\terrs = errors.Join(errs, fmt.Errorf(\"field `%s.hostSocket` must be less than UNIX_PATH_MAX=%d characters, but is %d\",\n\t\t\t\tfield, osutil.UnixPathMax, len(rule.HostSocket)))\n\t\t}","sourceCodeStart":339,"sourceCodeEnd":375,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/limayaml/validate.go#L339-L375","documentation":"A guestSocket target is a single host endpoint. If the host side is a port range (hostSocket empty and hostPortRange spans more than one port), Lima cannot decide which host port the single guest socket maps to, so validation fails.","triggerScenarios":"Validate on a LimaYAML where portForwards[i].GuestSocket != \"\", HostSocket == \"\", and HostPortRange[1]-HostPortRange[0] > 0 (e.g. hostPortRange: [8080, 8085] with guestSocket set).","commonSituations":"Adding guestSocket to an existing multi-port forwarding rule without narrowing hostPortRange; converting a range rule to socket forwarding by only adding the socket field.","solutions":["Collapse hostPortRange to a single port, e.g. [8080, 8080]","Or add a matching hostSocket instead of a host port range","Split into multiple rules, one per host port"],"exampleFix":"// before\nportForwards:\n  - guestSocket: /tmp/app.sock\n    hostPortRange: [8080, 8085]\n// after\nportForwards:\n  - guestSocket: /tmp/app.sock\n    hostPortRange: [8080, 8080]","handlingStrategy":"validation","validationCode":"for i, rule := range y.PortForwards {\n  if rule.GuestSocket != \"\" && rule.HostSocket == \"\" && rule.HostPortRange[1]-rule.HostPortRange[0] > 0 {\n    return fmt.Errorf(\"portForwards[%d]: guestSocket needs a single host port\", i)\n  }\n}","typeGuard":"func singleHostPort(rule limatype.PortForward) bool { return rule.HostSocket != \"\" || rule.HostPortRange[1]-rule.HostPortRange[0] == 0 }","tryCatchPattern":"if err := limayaml.Validate(y, false); err != nil {\n  if strings.Contains(err.Error(), \"guestSocket` can only be mapped to a single port\") {\n    // narrow hostPortRange to a single port\n  }\n}","preventionTips":["When adding guestSocket, collapse hostPortRange to [n, n]","Use hostSocket instead of a host port range for socket targets","Keep socket rules separate from range rules"],"tags":["lima","port-forwarding","unix-socket","config-validation"],"backgroundTag":"socket-port-range-mismatch","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}