field `mounts[%d].mountPoint` is the reserved internal home

Error message

field `mounts[%d].mountPoint` is the reserved internal home directory %#q

What it means

The guest user's home directory (defined via cidata user-data, `y.User.Home`) is reserved; mounting anything over it would shadow the guest's home (dotfiles, ssh keys, provisioning). Validate() rejects a mountPoint exactly equal to it.

Source

Thrown at pkg/limayaml/validate.go:151

		}
		st, err := os.Stat(loc)
		if err != nil {
			if !errors.Is(err, os.ErrNotExist) {
				errs = errors.Join(errs, fmt.Errorf("field `mounts[%d].location` refers to an inaccessible path: %#q: %w", i, f.Location, err))
			}
			if warn {
				logrus.Warnf("field `mounts[%d].location` refers to a non-existent directory: %#q:", i, f.Location)
			}
		} else if !st.IsDir() {
			errs = errors.Join(errs, fmt.Errorf("field `mounts[%d].location` refers to a non-directory path: %#q: %w", i, f.Location, err))
		}

		switch *f.MountPoint {
		case "/", "/bin", "/dev", "/etc", "/home", "/opt", "/sbin", "/tmp", "/usr", "/var":
			errs = errors.Join(errs, fmt.Errorf("field `mounts[%d].mountPoint` must not be a system path such as /etc or /usr", i))
		// home directory defined in "cidata.iso:/user-data"
		case *y.User.Home:
			errs = errors.Join(errs, fmt.Errorf("field `mounts[%d].mountPoint` is the reserved internal home directory %#q", i, *y.User.Home))
		}
		// There is no tilde-expansion for guest filenames
		if strings.HasPrefix(*f.MountPoint, "~") {
			errs = errors.Join(errs, fmt.Errorf("field `mounts[%d].mountPoint` must not start with `~`", i))
		}

		if _, err := units.RAMInBytes(*f.NineP.Msize); err != nil {
			errs = errors.Join(errs, fmt.Errorf("field `msize` has an invalid value: %w", err))
		}
	}

	if *y.SSH.LocalPort != 0 {
		if err := validatePort("ssh.localPort", *y.SSH.LocalPort); err != nil {
			errs = errors.Join(errs, err)
		}
	}

	if y.MountType != nil {

View on GitHub (pinned to dd909d0973)

Solutions

Set mountPoint to a subdirectory of home, e.g. `/home/<user>.linux/data`, or a non-home path like `/mnt/host`
Remove the explicit mountPoint if a default is acceptable
Re-validate the template after adjusting

Example fix

// before
mounts:
  - location: ~/data
    mountPoint: /home/user.linux
// after
mounts:
  - location: ~/data
    mountPoint: /home/user.linux/data

Defensive patterns

Strategy: validation

Validate before calling

function notGuestHome(mp, guestHome) { return typeof mp === 'string' && mp !== guestHome } // guestHome is typically /home/<user>.linux

Try / catch

try { await limactl(['template','validate', file]) } catch (e) { if (/reserved internal home directory/.test(e.message)) { nestUnderHome(e.message); } else throw e }

Prevention

Never mount directly over the guest user's home; use a subdirectory
Check the resolved guest home in the instance after first start
Document guest home path for the team's shared templates

When it happens

Trigger: A mounts entry's mountPoint equals the guest user home path (typically `/home/<user>.linux`) when Validate runs.

Common situations: Assuming mountPoint `~` or `/home/username` maps to the guest home and writing it explicitly; copying mounts from a setup with a different guest username where the path collided.

Related errors

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