field `%s.hostSocket` must be an absolute path, but is %#q

Error message

field `%s.hostSocket` must be an absolute path, but is %#q

What it means

hostSocket is a host filesystem path and must be absolute (filepath.IsAbs). The comment in the source notes this should normally be unreachable because FillDefault() prepends the instance directory to relative names, so hitting it usually means Validate was called without FillDefault or the path was malformed.

Source

Thrown at pkg/limayaml/validate.go:363

		}
		if rule.GuestPortRange[0] > rule.GuestPortRange[1] {
			errs = errors.Join(errs, fmt.Errorf("field `%s.guestPortRange[1]` must be greater than or equal to field `%s.guestPortRange[0]`", field, field))
		}
		if rule.HostPortRange[0] > rule.HostPortRange[1] {
			errs = errors.Join(errs, fmt.Errorf("field `%s.hostPortRange[1]` must be greater than or equal to field `%s.hostPortRange[0]`", field, field))
		}
		if rule.GuestSocket != "" {
			if !path.IsAbs(rule.GuestSocket) {
				errs = errors.Join(errs, fmt.Errorf("field `%s.guestSocket` must be an absolute path, but is %#q", field, rule.GuestSocket))
			}
			if rule.HostSocket == "" && rule.HostPortRange[1]-rule.HostPortRange[0] > 0 {
				errs = errors.Join(errs, fmt.Errorf("field `%s.guestSocket` can only be mapped to a single port or socket. not a range", field))
			}
		}
		if rule.HostSocket != "" {
			if !filepath.IsAbs(rule.HostSocket) {
				// should be unreachable because FillDefault() will prepend the instance directory to relative names
				errs = errors.Join(errs, fmt.Errorf("field `%s.hostSocket` must be an absolute path, but is %#q", field, rule.HostSocket))
			}
			if rule.GuestSocket == "" && rule.GuestPortRange[1]-rule.GuestPortRange[0] > 0 {
				errs = errors.Join(errs, fmt.Errorf("field `%s.hostSocket` can only be mapped from a single port or socket. not a range", field))
			}
		} else if rule.GuestPortRange[1]-rule.GuestPortRange[0] != rule.HostPortRange[1]-rule.HostPortRange[0] {
			errs = errors.Join(errs, fmt.Errorf("field `%s.hostPortRange` must specify the same number of ports as field `%s.guestPortRange`", field, field))
		}

		if len(rule.HostSocket) >= osutil.UnixPathMax {
			errs = errors.Join(errs, fmt.Errorf("field `%s.hostSocket` must be less than UNIX_PATH_MAX=%d characters, but is %d",
				field, osutil.UnixPathMax, len(rule.HostSocket)))
		}
		switch rule.Proto {
		case limatype.ProtoTCP, limatype.ProtoUDP, limatype.ProtoAny:
		default:
			errs = errors.Join(errs, fmt.Errorf("field `%s.proto` must be %#q, %#q, or %#q", field, limatype.ProtoTCP, limatype.ProtoUDP, limatype.ProtoAny))
		}
		if rule.Reverse && rule.GuestSocket == "" {

View on GitHub (pinned to dd909d0973)

Solutions

Run FillDefault() on the LimaYAML before calling Validate
Replace the hostSocket with an absolute path (e.g. /home/user/.lima/instance/sock)
If using limactl normally, this is a bug indicator — check the lima version

Example fix

// before
y, _ := limayaml.Load(b, "f.yaml")
limayaml.Validate(y, false)
// after
y, _ := limayaml.Load(b, "f.yaml")
limayaml.FillDefault(y)
limayaml.Validate(y, false)

Defensive patterns

Strategy: validation

Validate before calling

for i, rule := range y.PortForwards {
  if rule.HostSocket != "" && !filepath.IsAbs(rule.HostSocket) {
    return fmt.Errorf("portForwards[%d]: hostSocket must be absolute", i)
  }
}

Type guard

func hostSocketAbsolute(p string) bool { return p == "" || filepath.IsAbs(p) }

Try / catch

if err := limayaml.Validate(y, false); err != nil {
  if strings.Contains(err.Error(), "hostSocket` must be an absolute path") {
    // call limayaml.FillDefault(y) or absolutize the path
  }
}

Prevention

Always call FillDefault() before Validate when using the package programmatically
Store absolute hostSocket paths in templates
Treat this error in normal limactl usage as a bug report trigger

When it happens

Trigger: Validate on a LimaYAML where portForwards[i].HostSocket is non-empty and relative — typically when Validate is invoked on a struct that skipped FillDefault, or in tests/custom tooling that builds LimaYAML directly.

Common situations: Programmatic use of the limayaml package that calls Validate before FillDefault; constructing LimaYAML in tests with relative socket paths; unusual paths that evade defaulting.

Related errors

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