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

The host implementation explicitly specified in your Vagrant

Error message

The host implementation explicitly specified in your Vagrantfile
("%{value}") could not be found. Please verify that the plugin is
installed which implements this host and that the value you used
for `config.vagrant.host` is correct.

What it means

Raised as Vagrant::Errors::HostExplicitNotDetected from Vagrant::Environment#host (lib/vagrant/environment.rb:594). When config.vagrant.host is set to an explicit value, Host.new(...) raises CapabilityHostExplicitNotDetected (capability_host.rb:35) because no registered host plugin matches that name, and the environment converts it into this friendlier error carrying the configured value. Note the contrast: plain detection failure (:detect or nil) falls back to a generic capability-less host instead of raising.

Source

Thrown at lib/vagrant/environment.rb:594

        @host = Host.new(
          host_klass,
          Vagrant.plugin("2").manager.hosts,
          Vagrant.plugin("2").manager.host_capabilities,
          self)
      rescue Errors::CapabilityHostNotDetected
        # If the auto-detect failed, then we create a brand new host
        # with no capabilities and use that. This should almost never happen
        # since Vagrant works on most host OS's now, so this is a "slow path"
        klass = Class.new(Vagrant.plugin("2", :host)) do
          def detect?(env); true; end
        end

        hosts     = { generic: [klass, nil] }
        host_caps = {}

        @host = Host.new(:generic, hosts, host_caps, self)
      rescue Errors::CapabilityHostExplicitNotDetected => e
        raise Errors::HostExplicitNotDetected, e.extra_data
      end
    end

    # This acquires a process-level lock with the given name.
    #
    # The lock file is held within the data directory of this environment,
    # so make sure that all environments that are locking are sharing
    # the same data directory.
    #
    # This will raise Errors::EnvironmentLockedError if the lock can't
    # be obtained.
    #
    # @param [String] name Name of the lock, since multiple locks can
    #   be held at one time.
    def lock(name="global", **opts)
      f = nil

      # If we don't have a block, then locking is useless, so ignore it

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Remove or comment out the config.vagrant.host line — auto-detection is correct for almost every setup
2. If the explicit host is required, install the plugin that registers it (vagrant plugin install <name>) and confirm with `vagrant plugin list`
3. Use the exact registered host symbol (:darwin, :windows, :linux, ...) rather than an invented name
4. Re-run `vagrant status` to confirm the host now resolves

Example fix

# before
config.vagrant.host = "my_custom_host"   # plugin that defined it is not installed

# after
config.vagrant.host = :darwin             # a registered host — or delete the line to autodetect

host_name = env.vagrantfile.config.vagrant.host
registered = Vagrant.plugin("2").manager.hosts.keys
if host_name && host_name != :detect && !registered.include?(host_name.to_sym)
  raise ArgumentError, "config.vagrant.host=#{host_name} unknown; registered: #{registered.inspect}"
end

begin
  host = env.host
rescue Vagrant::Errors::HostExplicitNotDetected => e
  abort "Host #{e.extra_data[:value]} not found — install its plugin or remove config.vagrant.host"
end

When it happens

Trigger: A Vagrantfile with config.vagrant.host = :myhost (or "myhost") where :myhost is not in Vagrant.plugin("2").manager.hosts — the plugin providing the host is not installed, the name is misspelled, or the host class was removed in a newer Vagrant release. Any command that touches env.host (most commands) triggers it.

Common situations: Vagrantfiles copied from machines that had a host-detection plugin installed; pinning config.vagrant.host = :windows on a Linux-only Vagrant install; upgrading Vagrant after deprecated host classes (e.g. old :bsd/:arch variants) were dropped.

Related errors

• The guest implementation explicitly specified in your Vagran
• The explicit capability host specified of '%{value}' could n
• Vagrant attempted to execute the capability '%{cap}' on the
• There are errors in the configuration of this machine. Pleas
• The defined alias is not valid. Please review the informatio

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