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

NFS requires a host-only network to be created. Please add a

Error message

NFS requires a host-only network to be created.
Please add a host-only network to the machine (with either DHCP or a
static IP) for NFS to work.

What it means

Before writing NFS exports, the action locates the host's host-only adapter IP (host_ip) and the machine's IPs, then keeps only machine IPs that fall inside the host adapter's network. If either side ends up nil it raises NFSNoHostonlyNetwork: NFS mounting between host and guest needs both endpoints on a host-only network.

Source

Thrown at plugins/providers/virtualbox/action/prepare_nfs_settings.rb:83

          if host_ip && !machine_ip.empty?
            interface = @machine.provider.driver.read_host_only_interfaces.detect do |iface|
              iface[:ip] == host_ip
            end
            host_ipaddr = IPAddr.new("#{host_ip}/#{interface.fetch(:netmask, "0.0.0.0")}")

            case machine_ip
            when String
              machine_ip = nil if !host_ipaddr.include?(machine_ip)
            when Array
              machine_ip.delete_if do |m_ip|
                !host_ipaddr.include?(m_ip)
              end
              machine_ip = nil if machine_ip.empty?
            end
          end

          raise Vagrant::Errors::NFSNoHostonlyNetwork if !host_ip || !machine_ip

          env[:nfs_host_ip]    = host_ip
          env[:nfs_machine_ip] = machine_ip
        end

        # Finds first host only network adapter and returns its adapter number
        # and IP address
        #
        # @return [Integer, String] adapter number, ip address of found host-only adapter
        def find_host_only_adapter
          @machine.provider.driver.read_network_interfaces.each do |adapter, opts|
            if opts[:type] == :hostonly
              @machine.provider.driver.read_host_only_interfaces.each do |interface|
                if interface[:name] == opts[:hostonly]
                  return adapter, interface[:ip]
                end
              end
            end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Add a private network: `config.vm.network 'private_network', ip: '192.168.56.10'` (static is most reliable for NFS)
2. Check the host side matches: `VBoxManage list hostonlyifs` shows the adapter IP; the guest IP must be in that subnet (fix adapter ipconfig or the Vagrantfile ip)
3. If you do not need NFS, drop `type: 'nfs'` and use the default rsync/virtualbox folder type
4. Re-create the host-only network (delete + recreate in Host Network Manager) if its IP drifted, then `vagrant reload`

Example fix

# Vagrantfile - before:
config.vm.synced_folder '.', '/vagrant', type: 'nfs'   # no private network defined

# after:
config.vm.network 'private_network', ip: '192.168.56.10'
config.vm.synced_folder '.', '/vagrant', type: 'nfs'

# before enabling nfs synced folders, ensure a host-only network exists
has_private = vagrantfile_networks.any? { |n| n[:ip] || n[:type].to_s == 'dhcp' && n[:virtualbox__intnet].nil? }
using_nfs = vagrantfile_synced_folders.any? { |_, o| o[:type].to_s == 'nfs' }
abort 'NFS needs a private_network - add config.vm.network' if using_nfs && !has_private

begin
  env.cli('up')
rescue Vagrant::Errors::NFSNoHostonlyNetwork
  warn 'Add config.vm.network :private_network with a static ip, or drop type: "nfs"'
end

When it happens

Trigger: `vagrant up` with an NFS-typed synced folder (`config.vm.synced_folder '.', '/vagrant', type: 'nfs'`) while the VM has no host-only adapter, or its private-network IP sits outside the host adapter's subnet (e.g. host-only adapter on the host renumbered after upgrades).

Common situations: Adding nfs folders to a Vagrantfile that never defined a private_network; host-only adapter IP changed by VirtualBox or another tool so host_ipaddr.include?(machine_ip) fails; DHCP private networks where the guest got an address on a different range; switching from VirtualBox provider (hostonly) to another provider semantics.

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
• Network settings specified in your Vagrantfile define an inv
• The IP address configured for the host-only network is not w

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