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

The capability '%{cap}' is invalid. This is an internal erro

Error message

The capability '%{cap}' is invalid. This is an internal error that users should never see. Please report a bug.

What it means

CapabilityInvalid is raised in CapabilityHost#capability (lib/vagrant/capability_host.rb:106) when a capability module was found but cap_mod.method(cap_name) raises NameError — the registered module does not actually define a method matching the capability name. It indicates a misimplemented capability (registration and method name disagree), hence the internal-error wording.

Source

Thrown at lib/vagrant/capability_host.rb:106

    # Executes the capability with the given name, optionally passing more
    # arguments onwards to the capability. If the capability returns a value,
    # it will be returned.
    #
    # @param [Symbol] cap_name Name of the capability
    def capability(cap_name, *args)
      cap_mod = capability_module(cap_name.to_sym)
      if !cap_mod
        raise Errors::CapabilityNotFound,
          cap:  cap_name.to_s,
          host: @cap_host_chain[0][0].to_s
      end

      cap_method = nil
      begin
        cap_method = cap_mod.method(cap_name)
      rescue NameError
        raise Errors::CapabilityInvalid,
          cap: cap_name.to_s,
          host: @cap_host_chain[0][0].to_s
      end

      args = @cap_args + args
      @cap_logger.info(
        "Execute capability: #{cap_name} #{args.inspect} (#{@cap_host_chain[0][0]})")
      cap_method.call(*args)
    end

    protected

    def autodetect_capability_host(hosts, *args)
      @cap_logger.info("Autodetecting host type for #{args.inspect}")

      # Get the mapping of hosts with the most parents. We start searching
      # with the hosts with the most parents first.
      parent_count = {}

View on GitHub (pinned to 35f3160f4a)

Solutions

Update or reinstall the plugin providing the capability ('vagrant plugin update <name>' / uninstall + install)
If you own the plugin, define the method with exactly the same name as the registered capability symbol in the module
Report to the plugin maintainer with the capability name and host shown in the error, since users are not expected to see this

Example fix

# before (plugin capability module)
module MyCap
  def self.configure_networkss(machine)  # typo: name mismatch
  end
end

# after
module MyCap
  def self.configure_networks(machine)
  end
end

Defensive patterns

Strategy: try-catch

Try / catch

begin
  machine.guest.capability(:configure_networks, networks)
rescue Vagrant::Errors::CapabilityInvalid => e
  # registration/method mismatch in plugin — degrade gracefully
  logger.warn("capability misimplemented: #{e.message}")
  configure_networks_fallback(machine, networks)
end

Prevention

In your own plugins, unit-test that each registered capability module defines a method of the same name
Smoke-test plugin upgrades against the Vagrant version in production before rollout

When it happens

Trigger: capability(cap_name) resolves a module via capability_module, then Ruby's method lookup fails — e.g. a plugin registers a capability module under :configure_networks but the module defines configure_networks! or networks_configure; also after renames where the registration key was updated but the method was not.

Common situations: Third-party or in-house plugins whose capability modules misspell the method; plugins broken by Vagrant API changes; partial plugin upgrades (new registration, old code).

Related errors

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