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

The specified host network could not be found: '%{name}.' If

Error message

The specified host network could not be found: '%{name}.'
If the name specification is removed, Vagrant will create a new
host only network for you. Alternatively, please create the
specified network manually.

What it means

hostonly_adapter tries to find an existing host-only network matching the config (hostonly_find_matching_network). If none matches and the config carries an explicit :name, Vagrant raises NetworkNotFound rather than silently creating a different network — the name pin means the user expects that exact interface to exist.

Source

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

            mac:         options[:mac],
            name:        options[:name],
            netmask:     options[:netmask],
            nic_type:    options[:nic_type],
            type:        options[:type]
          }.merge(dhcp_options)
        end

        def hostonly_adapter(config)
          @logger.info("Searching for matching hostonly network: #{config[:ip]}")
          interface = hostonly_find_matching_network(config)

          if !interface
            @logger.info("Network not found. Creating if we can.")

            # It is an error if a specific host only network name was specified
            # but the network wasn't found.
            if config[:name]
              raise Vagrant::Errors::NetworkNotFound, name: config[:name]
            end

            # Create a new network
            interface = hostonly_create_network(config)
            @logger.info("Created network: #{interface[:name]}")
          end

          if config[:type] == :dhcp
            create_dhcp_server_if_necessary(interface, config)
          end

          return {
            adapter:     config[:adapter],
            hostonly:    interface[:name],
            mac_address: config[:mac],
            nic_type:    config[:nic_type],
            type:        :hostonly
          }

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Create the interface first: VirtualBox GUI > File > Host Network Manager > Create, or `VBoxManage hostonlyif create` (then `VBoxManage hostonlyif ipconfig <name> --ip ...`)
2. Remove the name: option so Vagrant creates/uses a matching host-only network automatically
3. Fix the name to one that exists: list with `VBoxManage list hostonlyifs`
4. After VirtualBox upgrades, re-check names — they are renumbered and stale names in Vagrantfiles break

Example fix

# before:
config.vm.network 'private_network', ip: '192.168.56.10',
  name: 'VirtualBox Host-Only Ethernet Adapter #3'  # doesn't exist

# after (let Vagrant manage it):
config.vm.network 'private_network', ip: '192.168.56.10'
# or create it: VBoxManage hostonlyif create && VBoxManage hostonlyif ipconfig vboxnet0 --ip 192.168.56.1

def hostonly_name_exists?(name)
  `VBoxManage list hostonlyifs`.lines.any? { |l| l =~ /^(Name|DisplayName):\s+#{Regexp.escape(name)}$/ }
end
abort "host-only interface '#{n}' not found" unless hostonly_name_exists?(n)

begin
  env.cli('up')
rescue Vagrant::Errors::NetworkNotFound => e
  warn "Create #{e.extra_data[:name]} (VBoxManage hostonlyif create) or drop the name: option"
end

When it happens

Trigger: `config.vm.network 'private_network', ip: ..., name: '<name>'` (or virtualbox__hostonly_adapter style options) where no host-only interface with that name or display name exists on the host; occurs during `vagrant up`/`reload` network setup.

Common situations: Vagrantfiles naming a host-only interface that was deleted or exists only on a teammate's machine; names copied from another host where VirtualBox assigned vboxnet0 vs VirtualBox Host-Only Ethernet Adapter #2; host-only networks wiped by a VirtualBox upgrade/reinstall.

Related errors

• The specified host network collides with a non-hostonly netw
• NFS requires a host-only network to be created. Please add a
• Network settings specified in your Vagrantfile define an inv
• The IP address configured for the host-only network is not w
• Could not find a required VirtualBox guest property: %{gue

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