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

The capability '%{cap}' could not be found. This is an inter

Error message

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

What it means

CapabilityNotFound is raised in CapabilityHost#capability (lib/vagrant/capability_host.rb:97) when capability_module(cap_name.to_sym) returns nil, i.e. no module anywhere in the resolved capability host chain provides that capability name. The error includes the capability and the primary host, and is documented as an internal error users should not see — hitting it usually means a missing/outdated plugin or a bad capability call.

Source

Thrown at lib/vagrant/capability_host.rb:97

    end

    # Tests whether the given capability is possible.
    #
    # @param [Symbol] cap_name Capability name
    # @return [Boolean]
    def capability?(cap_name)
      !capability_module(cap_name.to_sym).nil?
    end

    # 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

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Update Vagrant and all plugins to matching versions: 'vagrant plugin update' (and upgrade Vagrant itself)
2. If it comes from your own code, guard the call with capability?(cap_name) before invoking (the predicate exists right above the raise)
3. Verify the capability name and which plugin provides it in that plugin's source; install the missing plugin
4. Otherwise report a bug with the stack trace, since the message marks it internal

Example fix

# before
machine.guest.capability(:insert_public_key)

# after
if machine.guest.capability?(:insert_public_key)
  machine.guest.capability(:insert_public_key)
end

# built-in predicate: checks the capability chain resolves a module
return unless machine.guest.capability?(:insert_public_key)
machine.guest.capability(:insert_public_key)

When it happens

Trigger: Calling capability(:some_cap) on a guest/host/provider chain where no registered module defines it — e.g. plugin code or a Vagrantfile-adjacent script invoking machine.guest.capability(:not_a_real_cap), or core code calling a capability that only exists when an optional plugin (e.g. a provider guest plugin) is installed.

Common situations: Plugins skipped in an expunge/reinstall; version skew where an action expects a capability added in a newer plugin; typos in capability names in custom plugins; capabilities that are provider-specific called on the wrong provider.

Related errors

• The capability '%{cap}' is invalid. This is an internal erro
• Vagrant attempted to execute the capability '%{cap}' on the
• Vagrant failed to load a configured plugin source. This can
• The host implementation explicitly specified in your Vagrant
• There are no push strategies named '%{name}'. Please make su

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