lima-vm/lima · error

failed to mount fstab entry %v: %w

Error message

failed to mount fstab entry %v: %w

What it means

Raised by processUserData in the fakecloudinit guest agent (macOS) when one mounts entry from the cloud-init user-data cannot be mounted. It wraps the specific underlying error from mountFSTabEntry, which validates the fstab entry format and performs the mount (virtiofs only). The original entry is included in the message for diagnosis.

Source

Thrown at pkg/guestagent/fakecloudinit/fakecloudinit_darwin.go:111

		return fmt.Errorf("failed to unmarshal user data YAML: %w", err)
	}

	var errs []error
	if userData.Growpart != nil {
		logrus.Warn("growpart is not implemented")
	}
	if userData.PackageUpdate {
		logrus.Warn("package_update is not implemented")
	}
	if userData.PackageUpgrade {
		logrus.Warn("package_upgrade is not implemented")
	}
	if userData.PackageRebootIfRequired {
		logrus.Warn("package_reboot_if_required is not implemented")
	}
	for _, m := range userData.Mounts {
		if err = mountFSTabEntry(m); err != nil {
			errs = append(errs, fmt.Errorf("failed to mount fstab entry %v: %w", m, err))
		}
	}
	if userData.Timezone != "" {
		if err = setTimezone(ctx, userData.Timezone); err != nil {
			errs = append(errs, fmt.Errorf("failed to set timezone: %w", err))
		}
	}
	for _, u := range userData.Users {
		if err := createUser(ctx, &u); err != nil {
			errs = append(errs, fmt.Errorf("failed to create user %#q: %w", u.Name, err))
		}
	}
	for _, entry := range userData.WriteFiles {
		if err := writeFiles(ctx, entry); err != nil {
			errs = append(errs, fmt.Errorf("failed to write file for path %#q: %w", entry.Path, err))
		}
	}
	if userData.ManageResolvConf && userData.ResolvConf != nil {

View on GitHub (pinned to dd909d0973)

Solutions

1. Inspect the wrapped error in the message; it states exactly which sub-step failed (field count, fs type, pseudo tag, or symlink).
2. Fix the mounts entry in the Lima YAML / user-data so it has exactly 6 fields: <src> <dst> <fstype> <opts> <dump> <passno>.
3. Use only `virtiofs` as the fstype on macOS; other filesystem types are unsupported by the fake cloud-init.
4. Ensure the destination dir does not already exist as a real file/directory, or is already a symlink pointing to /Volumes/My Shared Files/<tag>.
5. Remove or comment out mounts entries that are not needed for the instance to boot.

Example fix

// before (user-data mounts)
mounts:
  - ["/Users/foo/share", "/mnt/share", "9p"]
// after
mounts:
  - ["/Users/foo/share", "/mnt/share", "virtiofs", "ro", "0", "0"]

func validateMounts(mounts [][]string) error {
  for i, m := range mounts {
    if len(m) != 6 { return fmt.Errorf("mounts[%d]: need 6 fields, got %d", i, len(m)) }
    if m[2] != "virtiofs" { return fmt.Errorf("mounts[%d]: fstype %q unsupported on macOS", i, m[2]) }
    if strings.Contains(m[0], "/") { return fmt.Errorf("mounts[%d]: pseudo tag %q must not contain separators", i, m[0]) }
  }
  return nil
}

func isValidFSTabEntry(m []string) bool {
  return len(m) == 6 && m[2] == "virtiofs" && !strings.Contains(m[0], string(filepath.Separator))
}

if err := processUserData(ctx, mnt); err != nil {
  var entryErr *fstabError
  if errors.As(err, &entryErr) { /* inspect which mounts entry failed and skip/fix it */ }
}

When it happens

Trigger: A `mounts:` entry in the user-data cloud-config fails mountFSTabEntry: the entry does not have exactly 6 fields, its fstype is not `virtiofs`, the virtiofs pseudo tag contains a path separator, or creating/verifying the /Volumes symlink fails.

Common situations: Copying a Linux-style fstab line with fewer than 6 columns (e.g. omitting dump/passno), using an fstype like `9p` or `nfs` that the macOS fake cloud-init does not implement, or a destination directory that already exists as a non-symlink or points elsewhere.

Related errors

• unsupported filesystem type %#q for fstab entry: %v
• invalid pseudo tag for virtiofs: %#q
• unexpected symlink target for virtiofs mount source %#q: exp
• failed to create symlink from %#q to %#q: %w
• field `mountType` must be %#q or %#q for QEMU driver on macO

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