hashicorp/vagrant · error · Vagrant::Errors::NFSClientNotInstalledInGuest

No NFS client was detected as installed in your guest machin

Error message

No NFS client was detected as installed in your guest machine. This
is required for NFS synced folders to work. In addition to this, Vagrant
doesn't know how to automatically install NFS for your machine, so
you must do this manually.

What it means

With config.nfs.verify_installed (default true), enable asks the guest's nfs_client_installed capability whether an NFS client exists. If not installed and the guest also lacks an nfs_client_install capability, Vagrant raises NFSClientNotInstalledInGuest: the missing prerequisite was detected and Vagrant cannot auto-install it for that guest OS.

Source

Thrown at plugins/synced_folders/nfs/synced_folder.rb:56

        end
        return false if !raise_error
        raise Vagrant::Errors::NFSNotSupported
      end

      def prepare(machine, folders, opts)
        # Nothing is necessary to do before VM boot.
      end

      def enable(machine, folders, nfsopts)
        raise Vagrant::Errors::NFSNoHostIP if !nfsopts[:nfs_host_ip]
        raise Vagrant::Errors::NFSNoGuestIP if !nfsopts[:nfs_machine_ip]

        if machine.config.nfs.verify_installed
          if machine.guest.capability?(:nfs_client_installed)
            installed = machine.guest.capability(:nfs_client_installed)
            if !installed
              can_install = machine.guest.capability?(:nfs_client_install)
              raise Vagrant::Errors::NFSClientNotInstalledInGuest if !can_install
              machine.ui.info I18n.t("vagrant.actions.vm.nfs.installing")
              machine.guest.capability(:nfs_client_install)
            end
          end
        end

        machine_ip = nfsopts[:nfs_machine_ip]
        machine_ip = [machine_ip] if !machine_ip.is_a?(Array)

        # Prepare the folder, this means setting up various options
        # and such on the folder itself.
        folders.each { |id, opts| prepare_folder(machine, opts) }

        # Determine what folders we'll export
        export_folders = folders.dup
        export_folders.keys.each do |id|
          opts = export_folders[id]
          if opts.key?(:nfs_export) && !opts[:nfs_export]

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Install the NFS client in the guest manually (apt-get install nfs-common / yum install nfs-utils) and bake it into the box image
2. Add it via Packer/box build so future boots pass verification
3. Switch the folder type to virtualbox/rsync if the guest never needs NFS
4. Set config.nfs.verify_installed = false only if you are certain the client exists

Example fix

# before
config.vm.synced_folder ".", "/vagrant", type: "nfs"  # guest lacks nfs client

# after
config.vm.provision "shell", inline: "apt-get update && apt-get install -y nfs-common"
config.vm.synced_folder ".", "/vagrant", type: "nfs"  # requires reload after install

# Vagrantfile: install the client before NFS mounts matter
config.vm.provision "shell", inline: "apt-get install -y nfs-common || yum install -y nfs-utils"

def nfs_client_installable?(machine)
  machine.guest.capability?(:nfs_client_install)
end

begin
  env.cli(%w(up))
rescue Vagrant::Errors::NFSClientNotInstalledInGuest
  abort "Bake nfs-common/nfs-utils into the box, then vagrant reload"
end

When it happens

Trigger: Booting a guest whose distro has the nfs_client_installed capability but no nfs_client_install capability, without nfs-common/nfs-utils preinstalled, while mounting type: "nfs" synced folders.

Common situations: Minimal/custom bboxes with packages stripped; less common distros where Vagrant only detects, not installs; containers-as-VMs images.

Related errors

• "rsync" was not detected as installed in your guest machine.
• The synced folder type '%{type}' is reporting as unusable fo
• NFS is reporting that your exports file is invalid. Vagrant
• FreeBSD hosts do not support sharing directories with whites
• You have attempted to export the same nfs host path at %{hos

AI-assisted analysis of hashicorp/vagrant@35f3160f4a (2026-08-21). Data as JSON: /api/errors/aa6282c4ed2c8c5b. Report an issue: GitHub.