lima-vm/lima · error

field `mounts[%d].mountPoint` must not start with `~`

Error message

field `mounts[%d].mountPoint` must not start with `~`

What it means

The mountPoint field starts with `~`. Guest home expansion is not performed for mount points, so a literal tilde-prefixed path would be created inside the guest; use an absolute path instead.

Source

Thrown at pkg/limayaml/validate.go:155

				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 {
		switch *y.MountType {
		case limatype.REVSSHFS, limatype.NINEP, limatype.VIRTIOFS, limatype.WSLMount:
		default:
			errs = errors.Join(errs, fmt.Errorf("field `mountType` must be %#q or %#q or %#q, or %#q, got %#q", limatype.REVSSHFS, limatype.NINEP, limatype.VIRTIOFS, limatype.WSLMount, *y.MountType))

View on GitHub (pinned to dd909d0973)

Solutions

  1. Replace the tilde with the absolute guest home path, e.g. `/home/<user>.linux/data`
  2. Or use a non-home path like `/mnt/host-data`
  3. Re-validate with `limactl template validate`

Example fix

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

Strategy: validation

Validate before calling

function noTildeInMountPoint(mp) { return typeof mp === 'string' && !mp.startsWith('~') }

Type guard

function isGuestAbsolutePath(mp) { return typeof mp === 'string' && mp.startsWith('/') }

Try / catch

try { await limactl(['template','validate', file]) } catch (e) { if (/mountPoint.*must not start with `~`/.test(e.message)) { replaceTildeWithGuestHome(); } else throw e }

Prevention

When it happens

Trigger: A mounts entry has `mountPoint: ~/data` or similar when Validate runs.

Common situations: Assuming both location and mountPoint support `~`; copying the location's tilde syntax into mountPoint; older configs written for tools that expanded guest tildes.

Related errors

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