hashicorp/vagrant · error · Vagrant::Errors.VirtualBoxGuestPropertyNotFound

Could not find a required VirtualBox guest property: %{gue

Error message

Could not find a required VirtualBox guest property:
  %{guest_property}
This is an internal error that should be reported as a bug.

What it means

The VirtualBox 5.x driver reads the guest's IP from the guest property `/VirtualBox/GuestInfo/Net/<n>/V4/IP` (populated by VirtualBox Guest Additions inside the VM). After fetching it, Vagrant ignores values that look like a DHCP-server address (ending in .1) and then validates the result; if no usable IP remains, it raises VirtualBoxGuestPropertyNotFound blaming the property itself. In practice the property is missing or invalid because Guest Additions are absent, not running, or the guest has not finished booting.

Source

Thrown at plugins/providers/virtualbox/driver/version_5_0.rb:605

          # If we can't get the guest additions version by guest property, try
          # to get it from the VM info itself.
          info = execute("showvminfo", @uuid, "--machinereadable", retryable: true)
          info.split("\n").each do |line|
            return $1.to_s if line =~ /^GuestAdditionsVersion="(.+?)"$/
          end

          return nil
        end

        def read_guest_ip(adapter_number)
          ip = read_guest_property("/VirtualBox/GuestInfo/Net/#{adapter_number}/V4/IP")
          if ip.end_with?(".1")
            @logger.warn("VBoxManage guest property returned: #{ip}. Result resembles IP of DHCP server and is being ignored.")
            ip = nil
          end

          if !valid_ip_address?(ip)
            raise Vagrant::Errors::VirtualBoxGuestPropertyNotFound,
                  guest_property: "/VirtualBox/GuestInfo/Net/#{adapter_number}/V4/IP"
          end

          return ip
        end

        def read_guest_property(property)
          output = execute("guestproperty", "get", @uuid, property)
          if output =~ /^Value: (.+?)$/
            $1.to_s
          else
            raise Vagrant::Errors::VirtualBoxGuestPropertyNotFound, guest_property: property
          end
        end

        def read_host_only_interfaces
          execute("list", "hostonlyifs", retryable: true).split("\n\n").collect do |block|
            info = {}

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Ensure the VM is fully booted before re-running (`vagrant up` again often resolves it once the guest is up)
2. Install/update matching Guest Additions, e.g. add the vagrant-vbguest plugin (`vagrant plugin install vagrant-vbguest`)
3. Confirm the property exists: `VBoxManage guestproperty get <uuid> /VirtualBox/GuestInfo/Net/0/V4/IP` (repeat for the adapter number in the error)
4. Check the guest actually configured the interface (correct adapter number in the private_network config, DHCP working inside the guest)
5. As a last resort switch that network to a forwarded-port setup which does not need the guest property

Example fix

// Vagrantfile — before
config.vm.network "private_network", ip: "192.168.33.10" // guest additions missing -> IP never reported
// after — keep additions in sync automatically
//   $ vagrant plugin install vagrant-vbguest
config.vm.network "private_network", ip: "192.168.33.10"

prop = `VBoxManage guestproperty get #{uuid} /VirtualBox/GuestInfo/Net/#{adapter}/V4/IP`
return nil unless prop =~ /^Value: (\d+\.){3}\d+$/ && !prop.end_with?(".1\n")  # not yet ready; wait and retry

def guest_ip_ready?(uuid, adapter)
  out = `VBoxManage guestproperty get #{uuid} /VirtualBox/GuestInfo/Net/#{adapter}/V4/IP 2>/dev/null`
  m = out.match(/^Value: ((?:\d+\.){3}\d+)/)
  !m.nil? && !m[1].end_with?('.1')
end

When it happens

Trigger: read_guest_ip(adapter_number) is called (e.g. `vagrant up`/`vagrant reload` resolving host-only or forwarded-port networking) and read_guest_property returns nothing usable: the VM is powered off, guest additions are not installed, or the only value reported is the DHCP server IP which Vagrant deliberately filters out.

Common situations: Box shipped without matching Guest Additions (very common with third-party boxes); `vbguest` not installed so additions fall out of sync after VirtualBox upgrades; querying the IP too early in the boot sequence; host-only network on adapter 2 whose guest side is unconfigured.

Related errors

• No synced folder implementation is available for your synced
• Network settings specified in your Vagrantfile define an inv
• The specified host network collides with a non-hostonly netw
• The specified host network could not be found: '%{name}.' If
• NFS requires a host-only network to be created. Please add a

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