field `provision[%d].path` must be an absolute path

Error message

field `provision[%d].path` must be an absolute path

What it means

For provision modes `data` and `yq`, Lima writes/edits a file at a fixed location inside the guest, so `path` must be an absolute POSIX path. `limayaml.Validate` checks `path.IsAbs(*p.Path)` and fails when a relative path is given, because a relative path has no defined base directory inside the guest filesystem.

Source

Thrown at pkg/limayaml/validate.go:223

		}
		if p.Mode != limatype.ProvisionModeDependency && p.SkipDefaultDependencyResolution != nil {
			errs = errors.Join(errs, fmt.Errorf("field `provision[%d].mode` cannot set skipDefaultDependencyResolution, only valid on scripts of type %#q",
				i, limatype.ProvisionModeDependency))
		}

		if *y.OS == limatype.WINDOWS && (p.Mode == limatype.ProvisionModeAnsible || p.Mode == limatype.ProvisionModeBoot || p.Mode == limatype.ProvisionModeYQ) {
			errs = errors.Join(errs, fmt.Errorf("provision mode %#q is not supported on Windows VM", p.Mode))
		}

		// This can lead to fatal Panic if p.Path is nil, better to return an error here
		switch p.Mode {
		case limatype.ProvisionModeData, limatype.ProvisionModeYQ:
			if p.Path == nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` must not be empty when mode is %#q", i, p.Mode))
				return errs
			}
			if !path.IsAbs(*p.Path) {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].path` must be an absolute path", i))
			}
			if p.Mode == limatype.ProvisionModeData && p.Content == nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].content` must not be empty when mode is %#q", i, p.Mode))
			}
			if p.Mode == limatype.ProvisionModeYQ && p.Expression == nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].expression` must not be empty when mode is %#q", i, p.Mode))
			}
			// FillDefaults makes sure that p.Permissions is not nil
			if _, err := strconv.ParseInt(*p.Permissions, 8, 64); err != nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].permissions` must be an octal number: %w", i, err))
			}
		default:
			if (p.Script == nil || *p.Script == "") && p.Mode != limatype.ProvisionModeAnsible {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].script` must not be empty", i))
			}
			if p.Content != nil {
				errs = errors.Join(errs, fmt.Errorf("field `provision[%d].content` can only be set when mode is %#q", i, limatype.ProvisionModeData))
			}

View on GitHub (pinned to dd909d0973)

Solutions

Prefix the path with `/` and give the full guest-absolute location (e.g. /etc/motd.d/lima).
Replace a `~/...` path with the explicit absolute home path if the guest user is known, or use a script-mode provision to write to $HOME.
Re-run validation to confirm the path now passes.

Example fix

# before
- mode: data
  path: etc/sysctl.d/99-lima.conf
  content: "vm.swappiness=10"
# after
- mode: data
  path: /etc/sysctl.d/99-lima.conf
  content: "vm.swappiness=10"

Defensive patterns

Strategy: validation

Validate before calling

for i, p := range cfg.Provision {
	if p.Mode == "data" || p.Mode == "yq" {
		if p.Path != nil && !strings.HasPrefix(*p.Path, "/") {
			return fmt.Errorf("provision[%d]: path %q must be absolute", i, *p.Path)
		}
	}
}

Type guard

func isGuestAbsPath(p *string) bool {
	return p != nil && path.IsAbs(*p)
}

Try / catch

if err := limayaml.Validate(y, false, "config.yaml"); err != nil {
	if strings.Contains(err.Error(), "must be an absolute path") {
		return fmt.Errorf("rewrite provision path as a guest-absolute path: %w", err)
	}
	return err
}

Prevention

Write guest file paths starting with `/`; never reuse host-relative paths.
Remember `~` is not absolute for path.IsAbs; use an explicit /home/user/... path or a script.
Add a template lint rule that enforces absolute paths for data/yq provision entries.

When it happens

Trigger: Running any Validate-calling limactl command on a YAML where a provision entry with mode "data" or "yq" has a `path` like `etc/foo.conf`, `./foo.conf`, or a Windows-style/empty path that `path.IsAbs` rejects.

Common situations: Authoring the path relative to the project or template directory by habit; copying a host-relative path into the guest entry; tilde-prefixed paths (`~/x`) which are not absolute per path.IsAbs; typos that leave a leading slash off.

Related errors

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