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

The guest implementation explicitly specified in your Vagran

Error message

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

What it means

Raised as Vagrant::Errors::GuestExplicitNotDetected from Vagrant::Guest#detect! (lib/vagrant/guest.rb:38): when config.vm.guest is set explicitly, initialize_capabilities! (capability_host.rb:35) raises CapabilityHostExplicitNotDetected because no registered guest matches that name, and Guest converts it into this error carrying the configured value. Unlike auto-detection failure (which raises GuestNotDetected), the explicit name must exist in the guest registry.

Source

Thrown at lib/vagrant/guest.rb:38

  #
  # This system allows for maximum flexibility and pluginability for doing
  # guest OS specific operations.
  class Guest
    include CapabilityHost

    def initialize(machine, guests, capabilities)
      @capabilities = capabilities
      @guests       = guests
      @machine      = machine
    end

    # This will detect the proper guest OS for the machine and set up
    # the class to actually execute capabilities.
    def detect!
      guest_name = @machine.config.vm.guest
      initialize_capabilities!(guest_name, @guests, @capabilities, @machine)
    rescue Errors::CapabilityHostExplicitNotDetected => e
      raise Errors::GuestExplicitNotDetected, value: e.extra_data[:value]
    rescue Errors::CapabilityHostNotDetected
      raise Errors::GuestNotDetected
    end

    # See {CapabilityHost#capability}
    def capability(*args)
      super
    rescue Errors::CapabilityNotFound => e
      raise Errors::GuestCapabilityNotFound,
        cap: e.extra_data[:cap],
        guest: name
    rescue Errors::CapabilityInvalid => e
      raise Errors::GuestCapabilityInvalid,
        cap: e.extra_data[:cap],
        guest: name
    end

    # Returns the specified or detected guest type name.

View on GitHub (pinned to 35f3160f4a)

Solutions

Remove the config.vm.guest line and let Vagrant detect the guest from the box
If you must pin it, use a registered guest name (e.g. :ubuntu, :linux, :windows, :darwin) and fix the typo
Install the plugin that provides the guest: `vagrant plugin install <name>`
Re-run `vagrant up` / `vagrant ssh` to confirm detection succeeds

Example fix

# before
config.vm.guest = :coreos   # not registered in this Vagrant install

# after
config.vm.guest = :linux     # or delete the line to let Vagrant detect the OS from the box

Defensive patterns

Strategy: validation

Validate before calling

guest = env.vagrantfile.config.vm.guest
registered = Vagrant.plugin("2").manager.guests.keys
if guest && !registered.include?(guest.to_sym)
  raise ArgumentError, "config.vm.guest=#{guest} unknown; registered: #{registered.inspect}"
end

Try / catch

begin
  machine.guest.detect!
rescue Vagrant::Errors::GuestExplicitNotDetected => e
  abort "Guest #{e.extra_data[:value]} not found — fix config.vm.guest or install its plugin"
end

Prevention

Let Vagrant detect the guest from the box metadata; pin config.vm.guest only when necessary
Check plugin guest names with `vagrant plugin list` and docs before pinning
Re-test pinned guest names after every Vagrant/plugin upgrade

When it happens

Trigger: A Vagrantfile with config.vm.guest = :someos where :someos is not registered — the guest ships in a plugin that is not installed, the name is missyped, or the guest was removed/renamed in a newer Vagrant (e.g. distro guests that moved into plugins). Any action calling machine.guest.detect! (most up/provision/ssh flows) triggers it.

Common situations: Setting config.vm.guest to force an OS and mistyping it; Vagrantfiles written for plugin-provided guests (smartos, old coreos, etc.) on installs lacking the plugin; Vagrant upgrades renaming guest symbols.

Related errors

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