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

Error message

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

What it means

When a portForward rule uses guestSocket, the path is interpreted inside the guest filesystem and must be absolute (checked with path.IsAbs). A relative path like "tmp/app.sock" is ambiguous and rejected.

Source

Thrown at pkg/limayaml/validate.go:354

		for j := range 2 {
			if err := validatePort(fmt.Sprintf("%s.guestPortRange[%d]", field, j), rule.GuestPortRange[j]); err != nil {
				errs = errors.Join(errs, err)
			}
			if rule.HostSocket == "" {
				if err := validatePort(fmt.Sprintf("%s.hostPortRange[%d]", field, j), rule.HostPortRange[j]); err != nil {
					errs = errors.Join(errs, err)
				}
			}
		}
		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 {

View on GitHub (pinned to dd909d0973)

Solutions

Prefix the guestSocket value with '/' to make it an absolute guest path
Expand ~ to the absolute guest home path manually (Lima does not expand it)
Verify with `limactl template validate`

Example fix

// before
portForwards:
  - guestSocket: tmp/app.sock
    hostSocket: /tmp/app.sock
// after
portForwards:
  - guestSocket: /tmp/app.sock
    hostSocket: /tmp/app.sock

Defensive patterns

Strategy: validation

Validate before calling

for i, rule := range y.PortForwards {
  if rule.GuestSocket != "" && !strings.HasPrefix(rule.GuestSocket, "/") {
    return fmt.Errorf("portForwards[%d]: guestSocket must be an absolute guest path", i)
  }
}

Type guard

func guestSocketAbsolute(p string) bool { return p == "" || path.IsAbs(p) }

Try / catch

if err := limayaml.Validate(y, false); err != nil {
  if strings.Contains(err.Error(), "guestSocket` must be an absolute path") {
    // prepend '/' or expand the path
  }
}

Prevention

Always start guestSocket with '/'
Expand ~ yourself before writing the config
Remember guestSocket is a guest-filesystem path, not a host path

When it happens

Trigger: Validate on a LimaYAML where portForwards[i].GuestSocket is a non-empty string not starting with '/' (e.g. "tmp/sock" or "~/app.sock").

Common situations: Writing a guest socket path relative to home directory using ~; copying a Windows-style or relative path into the config; forgetting the leading slash when refactoring from port to socket forwarding.

Related errors

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