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

The synced folder type '%{type}' is reporting as unusable fo

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).

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)

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)

# 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

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

• The box you're attempting to add doesn't support the provide
• The box you're attempting to add doesn't support the request
• The box you're attempting to add doesn't support the request
• The box you're attempting to add has no available version th
• No synced folder implementation is available for your synced

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