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

The IP address configured for the host-only network is not w

Error message

The IP address configured for the host-only network is not within the
allowed ranges. Please update the address used to be within the allowed
ranges and run the command again.

  Address: %{address}
  Ranges: %{ranges}

Valid ranges can be modified in the /etc/vbox/networks.conf file. For
more information including valid format see:

  https://www.virtualbox.org/manual/ch06.html#network_hostonly

What it means

Since VirtualBox 6.1.28, Linux hosts enforce that host-only adapter IPs fall within ranges allowed by /etc/vbox/networks.conf. validate_hostonly_ip! runs on Linux with driver version >= 6.1.28 (skipped on Windows and on macOS >= 7.0.0), loads the allowed ranges (defaulting to 192.168.56.0/21 when the conf file is absent) and raises VirtualBoxInvalidHostSubnet when the configured IP is outside all of them.

Source

Thrown at plugins/providers/virtualbox/action/network.rb:560

          nil
        end

        # Validates the IP used to configure the network is within the allowed
        # ranges. It only validates if the network configuration file exists.
        # This was introduced in 6.1.28 so previous version won't have restrictions
        # placed on the valid ranges
        def validate_hostonly_ip!(ip, driver)
          return if Gem::Version.new(driver.version) < HOSTONLY_VALIDATE_VERSION ||
                    (
                      Vagrant::Util::Platform.darwin? &&
                      Gem::Version.new(driver.version) >= DARWIN_IGNORE_HOSTONLY_VALIDATE_VERSION
                    ) ||
                    Vagrant::Util::Platform.windows?

          ip = IPAddr.new(ip.to_s) if !ip.is_a?(IPAddr)
          valid_ranges = load_net_conf
          return if valid_ranges.any?{ |range| range.include?(ip) }
          raise Vagrant::Errors::VirtualBoxInvalidHostSubnet,
            address: ip,
            ranges: valid_ranges.map{ |r| "#{r}/#{r.prefix}" }.join(", ")
        end

        def load_net_conf
          return HOSTONLY_DEFAULT_RANGE if !File.exist?(VBOX_NET_CONF)
          File.readlines(VBOX_NET_CONF).map do |line|
            line = line.strip
            next if !line.start_with?("*")
            line[1,line.length].strip.split(" ").map do |entry|
              IPAddr.new(entry)
            end
          end.flatten.compact
        end

        #-----------------------------------------------------------------
        # DHCP Server Helper Functions
        #-----------------------------------------------------------------

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Change the private_network ip to one inside the default range (192.168.56.0–192.168.63.255, i.e. 192.168.56.0/21)
2. Or widen the allowed ranges: create /etc/vbox/networks.conf containing `* 10.0.0.0/8 192.168.0.0/16 172.16.0.0/12` (lines start with '*') and re-run
3. Keep /etc/vbox/networks.conf under config management so CI hosts match developer hosts
4. Check the printed Ranges value in the error to see exactly what is currently allowed

Example fix

# Vagrantfile - before (Linux + VBox >= 6.1.28, no networks.conf):
config.vm.network 'private_network', ip: '10.0.5.10'

# after (option A - move into default range):
config.vm.network 'private_network', ip: '192.168.56.10'

# after (option B - allow the range on the host):
# sudo tee /etc/vbox/networks.conf <<< '* 10.0.0.0/8 192.168.0.0/16'

require 'ipaddr'
def ip_in_vbox_ranges?(ip)
  ranges = if File.exist?('/etc/vbox/networks.conf')
    File.readlines('/etc/vbox/networks.conf').grep(/^\*/).flat_map { |l| l[1..].strip.split.map { |e| IPAddr.new(e) } }
  else
    [IPAddr.new('192.168.56.0/21')]
  end
  ranges.any? { |r| r.include?(IPAddr.new(ip.to_s)) }
end
abort 'ip outside allowed ranges' unless ip_in_vbox_ranges?('192.168.56.10')

begin
  env.cli('up')
rescue Vagrant::Errors::VirtualBoxInvalidHostSubnet => e
  warn "#{e.extra_data[:address]} outside #{e.extra_data[:ranges]} - update /etc/vbox/networks.conf or the ip"
end

When it happens

Trigger: `vagrant up` on Linux with VirtualBox >= 6.1.28 and a private_network ip like 10.0.5.10 or 192.168.100.10, while /etc/vbox/networks.conf does not exist — only the default 192.168.56.0/21 is permitted, so validate_hostonly_ip! raises before the adapter is configured.

Common situations: Upgrading VirtualBox past 6.1.28 on Linux breaks Vagrantfiles that always used 10.x or other RFC1918 ranges; CI images without /etc/vbox/networks.conf; teams porting Vagrantfiles from macOS/Windows hosts where the check is skipped.

Related errors

• 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
• No synced folder implementation is available for your synced
• The guest machine entered an invalid state while waiting for

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