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

The explicit capability host specified of '%{value}' could n

Error message

The explicit capability host specified of '%{value}' could not be found.

This is an internal error that users should never see. Please report a bug.

What it means

CapabilityHostExplicitNotDetected is raised in initialize_capabilities! (lib/vagrant/capability_host.rb:35) when an explicitly requested capability host symbol is not a key in the hosts registry hash. The framework (guests, hosts, providers all use CapabilityHost) was told 'use host X' but X is unknown, which for end users usually means a bad guest/host symbol in configuration.

Source

Thrown at lib/vagrant/capability_host.rb:35

  module CapabilityHost
    # Initializes the capability system by detecting the proper capability
    # host to execute on and building the chain of capabilities to execute.
    #
    # @param [Symbol] host The host to use for the capabilities, or nil if
    #   we should auto-detect it.
    # @param [Hash<Symbol, Array<Class, Symbol>>] hosts Potential capability
    #   hosts. The key is the name of the host, value[0] is a class that
    #   implements `#detect?` and value[1] is a parent host (if any).
    # @param [Hash<Symbol, Hash<Symbol, Class>>] capabilities The capabilities
    #   that are supported. The key is the host of the capability. Within that
    #   is a hash where the key is the name of the capability and the value
    #   is the class/module implementing it.
    def initialize_capabilities!(host, hosts, capabilities, *args)
      @cap_logger = Log4r::Logger.new(
        "vagrant::capability_host::#{self.class.to_s.downcase}")

      if host && !hosts[host]
        raise Errors::CapabilityHostExplicitNotDetected, value: host.to_s
      end

      if !host
        host = autodetect_capability_host(hosts, *args) if !host
        raise Errors::CapabilityHostNotDetected if !host
      end

      if !hosts[host]
        # This should never happen because the autodetect above uses the
        # hosts hash to look up hosts. And if an explicit host is specified,
        # we do another check higher up.
        raise "Internal error. Host not found: #{host}"
      end

      name      = host
      host_info = hosts[name]
      host      = host_info[0].new
      chain     = []

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Correct the symbol: use supported guests like :windows or :linux, or remove config.vm.guest entirely to let Vagrant autodetect
2. If the guest comes from a plugin, install/update that plugin so the host gets registered ('vagrant plugin install <plugin>')
3. Check the exact supported names for your Vagrant version in the docs/changelog before pinning

Example fix

# before (Vagrantfile)
config.vm.guest = :windos

# after
config.vm.guest = :windows

supported = %i[linux windows] # check docs for version-specific list
raise "unsupported guest #{guest_sym}" unless supported.include?(guest_sym)

When it happens

Trigger: initialize_capabilities!(host, hosts, capabilities, *args) is called with host non-nil and hosts[host] nil — e.g. Vagrantfile 'config.vm.guest = :windos' when Guest#new builds its capability host chain, or a plugin explicitly requesting an unregistered host class.

Common situations: Typos in config.vm.guest (e.g. :window instead of :windows); guest names removed/renamed across Vagrant versions (old :linux guest was removed); copy-pasted Vagrantfiles referencing plugin-provided guests whose plugin is not installed.

Related errors

• The guest implementation explicitly specified in your Vagran
• The capability host could not be detected. This is an intern
• The host implementation explicitly specified in your Vagrant
• Vagrant attempted to execute the capability '%{cap}' on the
• There are errors in the configuration of this machine. Pleas

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