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

Vagrant attempted to execute the capability '%{cap}' on the

Error message

Vagrant attempted to execute the capability '%{cap}'
on the detect guest OS '%{guest}', but the guest doesn't
support that capability. This capability is required for your
configuration of Vagrant. Please either reconfigure Vagrant to
avoid this capability or fix the issue by creating the capability.

What it means

The SMB synced folder's enable step first verifies the guest supports mount_smb_shared_folder; if machine.guest.capability?(:mount_smb_shared_folder) is false it raises GuestCapabilityNotFound with cap and guest name interpolated. SMB folders target Windows guests, so attaching one to a guest whose plugin lacks the mount capability aborts before mounting.

Source

Thrown at plugins/synced_folders/smb/synced_folder.rb:111

            data[:smb_username] = smb_username
          else
            data[:smb_username] ||= smb_username
          end
          data[:smb_password] ||= smb_password

          # Register password as sensitive
          Vagrant::Util::CredentialScrubber.sensitive(data[:smb_password])
        end

        machine.env.host.capability(:smb_prepare, machine, folders, opts)
      end

      def enable(machine, folders, opts)
        machine.ui.output(I18n.t("vagrant_sf_smb.mounting"))

        # Make sure that this machine knows this dance
        if !machine.guest.capability?(:mount_smb_shared_folder)
          raise Vagrant::Errors::GuestCapabilityNotFound,
            cap: "mount_smb_shared_folder",
            guest: machine.guest.name.to_s
        end

        # Setup if we have it
        if machine.guest.capability?(:smb_install)
          machine.guest.capability(:smb_install)
        end

        # Detect the host IP for this guest if one wasn't specified
        # for every folder.
        host_ip = nil
        need_host_ip = false
        folders.each do |id, data|
          if !data[:smb_host]
            need_host_ip = true
            break
          end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Use smb folders only with Windows guests; for Linux use nfs or virtualbox/rsync
2. Change the folder type: config.vm.synced_folder "src", "/srv", type: "nfs"
3. Install a guest plugin that provides the SMB/CIFS mount capability for your distro
4. Contribute the capability to the guest plugin, as the message suggests

Example fix

# before
config.vm.synced_folder "src", "/srv", type: "smb",
  smb_username: "...", smb_password: "..."   # linux guest -> capability missing

# after
config.vm.synced_folder "src", "/srv", type: "nfs"

# only use smb folders when the guest can mount them
return unless machine.guest.capability?(:mount_smb_shared_folder)

def smb_mountable?(machine)
  machine.guest.capability?(:mount_smb_shared_folder)
end

begin
  env.cli(%w(up))
rescue Vagrant::Errors::GuestCapabilityNotFound => e
  d = e.extra_data
  abort "#{d[:guest]} guest lacks #{d[:cap]} - use nfs/virtualbox folders"
end

When it happens

Trigger: config.vm.synced_folder ... type: "smb" on a Linux/other guest whose guest plugin does not register mount_smb_shared_folder (core Linux guests expect nfs/rsync/virtualbox, not SMB mounts).

Common situations: Porting a Windows-oriented Vagrantfile (with smb_username/smb_password) to a Linux box; choosing smb for host performance without checking guest support.

Related errors

• Vagrant is unable to setup a requested SMB share. An SMB sha
• Exporting an SMB share failed! Details about the failure are
• The synced folder type '%{type}' is reporting as unusable fo
• Vagrant attempted to execute the capability '%{cap}' on the
• Vagrant failed to automatically start the SMB service. Ensur

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