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

Raised as Vagrant::Errors::GuestCapabilityNotFound from Vagrant::Guest#capability (lib/vagrant/guest.rb:47): the underlying CapabilityHost#capability (capability_host.rb:97) raises CapabilityNotFound when no guest in the machine's guest chain provides the requested capability, and Guest re-raises it naming both the capability and the detected guest. It means the guest resolved, but it cannot perform the OS-specific operation some provider or plugin requires.

Source

Thrown at lib/vagrant/guest.rb:47

      @machine      = machine
    end

    # This will detect the proper guest OS for the machine and set up
    # the class to actually execute capabilities.
    def detect!
      guest_name = @machine.config.vm.guest
      initialize_capabilities!(guest_name, @guests, @capabilities, @machine)
    rescue Errors::CapabilityHostExplicitNotDetected => e
      raise Errors::GuestExplicitNotDetected, value: e.extra_data[:value]
    rescue Errors::CapabilityHostNotDetected
      raise Errors::GuestNotDetected
    end

    # See {CapabilityHost#capability}
    def capability(*args)
      super
    rescue Errors::CapabilityNotFound => e
      raise Errors::GuestCapabilityNotFound,
        cap: e.extra_data[:cap],
        guest: name
    rescue Errors::CapabilityInvalid => e
      raise Errors::GuestCapabilityInvalid,
        cap: e.extra_data[:cap],
        guest: name
    end

    # Returns the specified or detected guest type name.
    #
    # @return [Symbol]
    def name
      capability_host_chain[0][0]
    end

    # This returns whether the guest is ready to work. If this returns
    # `false`, then {#detect!} should be called in order to detect the
    # guest OS.

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Remove the manual config.vm.guest override so full detection rebuilds the guest chain with all parent capabilities
2. Update the provider/guest plugins — capabilities are frequently added and renamed across versions (vagrant plugin update / reinstall)
3. If you maintain the guest plugin, implement the named capability for that guest
4. As a stopgap, disable the feature that invokes the capability (e.g. config.vm.synced_folder ... , disabled: true for mount caps)

Example fix

# before
config.vm.guest = :minimal_linux    # custom guest lacking mount capabilities
config.vm.synced_folder ".", "/vagrant"

# after
config.vm.guest = :ubuntu            # full chain provides the mount capability
config.vm.synced_folder ".", "/vagrant"

# CapabilityHost#capability? (capability_host.rb:85) is the built-in guard
if machine.guest.capability?(:mount_virtualbox_shared_folder)
  machine.guest.capability(:mount_virtualbox_shared_folder, folder)
else
  raise "guest #{machine.guest.name} lacks the required capability"
end

begin
  machine.guest.capability(:configure_networks, networks)
rescue Vagrant::Errors::GuestCapabilityNotFound => e
  abort "Guest #{e.extra_data[:guest]} lacks capability '#{e.extra_data[:cap]}' — fix config.vm.guest or update plugins"
end

When it happens

Trigger: Overriding config.vm.guest to a minimal/wrong guest so the chain lacks a capability an action needs (e.g. synced-folder mounting caps when :linux is forced where :ubuntu was detected); outdated guest/provider plugins after a Vagrant upgrade where a capability was renamed or newly required; custom guest plugins that never implemented the capability.

Common situations: Manually pinning config.vm.guest to work around a detection issue and silently losing the parent guest chain's capabilities; version drift between Vagrant core and provider/guest plugins; boxes whose OS is newer than the plugin's guest definitions.

Related errors

• The guest implementation explicitly specified in your Vagran
• The explicit capability host specified of '%{value}' could n
• The capability '%{cap}' could not be found. This is an inter
• The capability '%{cap}' is invalid. This is an internal erro
• The host implementation explicitly specified in your Vagrant

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