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

The synced folder type

Error message

The synced folder type '%{type}' is reporting as unusable for
your current setup. Please verify you have all the proper
prerequisites for using this shared folder type and try again.

What it means

When a synced folder declares an explicit `type:` (nfs, rsync, smb, ...), Vagrant looks up the implementation plugin and calls `usable?(machine, true)`; if the implementation reports itself unusable on this host/guest combination, SyncedFolderUnusable is raised with that type. The usable? check encodes the prerequisites for the folder type (host tools, guest tools, platform support).

Solutions

  1. Install the prerequisites for that folder type (e.g. `apt-get install nfs-kernel-server` on the host; install rsync on both host and guest; enable the SMB/WinNFSD components).
  2. Or switch to a type that works everywhere: `type: "rsync"` is the portable fallback once rsync exists on host and guest.
  3. Or disable the folder if you do not need it: `config.vm.synced_folder ".", "/vagrant", disabled: true`.

Example fix

# before (NFS unusable on this host)
config.vm.synced_folder ".", "/vagrant", type: "nfs"

# after (portable)
config.vm.synced_folder ".", "/vagrant", type: "rsync",
  rsync__exclude: ".git/"
# ensure: sudo apt-get install -y rsync   (host + guest)
Defensive patterns

Strategy: validation

Validate before calling

# Verify the folder type's host prerequisites before `vagrant up`
case "$FOLDER_TYPE" in
  rsync) command -v rsync >/dev/null || { echo "install rsync on host"; exit 1; } ;;
  nfs)   command -v nfsd >/dev/null || command -v exportfs >/dev/null || { echo "NFS server missing"; exit 1; } ;;
esac
vagrant up

Prevention

When it happens

Trigger: Declaring e.g. `config.vm.synced_folder ".", "/vagrant", type: "nfs"` on a host where NFS serving is unavailable, `type: "rsync"` without rsync on host or guest, or `type: "smb"` with missing credentials — anything where the chosen impl's usable? returns false (lib/vagrant/action/builtin/mixin_synced_folders.rb:144-151).

Common situations: NFS on Windows without vagrant-winnfsd; NFS on a Linux host without nfs-kernel-server running; rsync missing in a minimal guest box; SMB credentials not set; using a folder type the guest OS cannot mount (e.g. vboxsf on FreeBSD guests).

Related errors

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

Appendix: source

Thrown at lib/vagrant/action/builtin/mixin_synced_folders.rb:149

            # Ignore disabled synced folders
            next if data[:disabled]

            impl = ""
            impl = data[:type].to_sym if data[:type] && !data[:type].empty?

            if impl != ""
              impl_class = plugins[impl]
              if !impl_class
                # This should never happen because configuration validation
                # should catch this case. But we put this here as an assert
                raise "Internal error. Report this as a bug. Invalid: #{data[:type]}"
              end

              if !opts[:disable_usable_check]
                if !impl_class[0].new.usable?(machine, true)
                  # Verify that explicitly defined shared folder types are
                  # actually usable.
                  raise Errors::SyncedFolderUnusable, type: data[:type].to_s
                end
              end
            end

            # Get the data to store
            data = data.dup
            if root
              # If these are the root synced folders (attached directly)
              # to the Vagrantfile, then we mark it as such.
              data[:__vagrantfile] = true
            end

            # Keep track of this shared folder by the implementation.
            folders[impl] ||= {}
            folders[impl][id] = data
          end

          # If we have folders with the "default" key, then determine the

View on GitHub (pinned to 35f3160f4a)