{"record":{"id":"d73fc3220cb36464","repo":"hashicorp/vagrant","slug":"the-capability-cap-is-invalid-this-is-an-int","errorCode":null,"errorMessage":"The capability '%{cap}' is invalid. This is an internal error that users should never see. Please report a bug.","messagePattern":"The capability '%(.+?)' is invalid\\. This is an internal error that users should never see\\. Please report a bug\\.","errorType":"exception","errorClass":"Vagrant::Errors::CapabilityInvalid","httpStatus":null,"severity":"error","filePath":"lib/vagrant/capability_host.rb","lineNumber":106,"sourceCode":"\n    # Executes the capability with the given name, optionally passing more\n    # arguments onwards to the capability. If the capability returns a value,\n    # it will be returned.\n    #\n    # @param [Symbol] cap_name Name of the capability\n    def capability(cap_name, *args)\n      cap_mod = capability_module(cap_name.to_sym)\n      if !cap_mod\n        raise Errors::CapabilityNotFound,\n          cap:  cap_name.to_s,\n          host: @cap_host_chain[0][0].to_s\n      end\n\n      cap_method = nil\n      begin\n        cap_method = cap_mod.method(cap_name)\n      rescue NameError\n        raise Errors::CapabilityInvalid,\n          cap: cap_name.to_s,\n          host: @cap_host_chain[0][0].to_s\n      end\n\n      args = @cap_args + args\n      @cap_logger.info(\n        \"Execute capability: #{cap_name} #{args.inspect} (#{@cap_host_chain[0][0]})\")\n      cap_method.call(*args)\n    end\n\n    protected\n\n    def autodetect_capability_host(hosts, *args)\n      @cap_logger.info(\"Autodetecting host type for #{args.inspect}\")\n\n      # Get the mapping of hosts with the most parents. We start searching\n      # with the hosts with the most parents first.\n      parent_count = {}","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/lib/vagrant/capability_host.rb#L88-L124","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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"],"exampleFix":"# before (plugin capability module)\nmodule MyCap\n  def self.configure_networkss(machine)  # typo: name mismatch\n  end\nend\n\n# after\nmodule MyCap\n  def self.configure_networks(machine)\n  end\nend","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"begin\n  machine.guest.capability(:configure_networks, networks)\nrescue Vagrant::Errors::CapabilityInvalid => e\n  # registration/method mismatch in plugin — degrade gracefully\n  logger.warn(\"capability misimplemented: #{e.message}\")\n  configure_networks_fallback(machine, networks)\nend","preventionTips":["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"],"tags":["vagrant","capability","plugin","method-missing","internal"],"backgroundTag":"plugin-capability-invalid","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}