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

Network settings specified in your Vagrantfile define an inv

Error message

Network settings specified in your Vagrantfile define an invalid
IP address. Please review the error message below and update your
Vagrantfile network settings:

  Address: %{address}
  Netmask: %{mask}
  Error: %{error}

What it means

While generating NetworkManager connection profiles inside the guest (lib/vagrant/util/guest_networks.rb), Vagrant validates the configured address with IPAddr#mask using the configured netmask; any IPAddr::Error (malformed address, invalid netmask, family mismatch such as an IPv4 mask on an IPv6 address) is re-raised as NetworkAddressInvalid with the address, mask, and original error text.

Source

Thrown at lib/vagrant/util/guest_networks.rb:56

            if net_opts[:type] != "dhcp"
              begin
                addr = IPAddr.new("#{net_opts[:ip]}")
                if addr.ipv4?
                  tmpl_opts[:ipv4] = addr.to_string
                  masked = addr.mask(net_opts[:netmask])

                  tmpl_opts[:ipv4_mask] = masked.prefix
                  tmpl_opts[:ipv4_gateway] = masked.succ.to_string
                else
                  tmpl_opts[:ipv6] = addr.to_string
                  masked = addr.mask(net_opts[:netmask])

                  tmpl_opts[:ipv6_mask] = masked.prefix
                  tmpl_opts[:ipv6_gateway] = masked.succ.to_string
                end
              rescue IPAddr::Error => err
                raise NetworkAddressInvalid,
                      address: net_opts[:ip],
                      mask: net_opts[:netmask],
                      error: err.to_s
              end
            end

            entry = TemplateRenderer.render("networking/network_manager/network_manager_device", options: tmpl_opts)
            remote_path = "/tmp/vagrant-network-entry-#{net_opts[:device]}-#{Time.now.to_i}-#{i}"
            final_path = "#{nm_directory}/#{net_opts[:device]}.nmconnection"

            Tempfile.open("vagrant-nm-configure-networks") do |f|
              f.binmode
              f.write(entry)
              f.fsync
              f.close
              comm.upload(f.path, remote_path)
            end

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Correct the ip/netmask so every octet is <= 255 and the mask is a valid contiguous netmask
  2. Prefer CIDR notation (ip: "192.168.50.10/24") to keep address and mask consistent
  3. For IPv6, use ipv6: with a proper prefix length instead of an IPv4 netmask
  4. Dry-validate locally: `require 'ipaddr'; IPAddr.new(ip).mask(netmask)` — if Ruby's IPAddr raises, Vagrant will too

Example fix

# before
config.vm.network "private_network", ip: "192.168.50.10", netmask: "255.255.300.0"

# after
config.vm.network "private_network", ip: "192.168.50.10/24"
Defensive patterns

Strategy: validation

Validate before calling

require 'ipaddr'

def valid_network?(ip, netmask)
  IPAddr.new(ip).mask(netmask)
  true
rescue IPAddr::Error
  false
end

abort 'bad network stanza' unless valid_network?('192.168.50.10', '255.255.255.0')

Try / catch

begin
  machine.env.lock { configure_networks }
rescue Vagrant::Errors::NetworkAddressInvalid => e
  d = e.extra_data # :address, :mask, :error
  machine.ui.error("fix #{d[:address]}/#{d[:mask]}: #{d[:error]}")
end

Prevention

When it happens

Trigger: `config.vm.network "private_network", ip: "192.168.50.999"` (invalid octet), a bad netmask like "255.255.300.0", or pairing ipv6: addresses with an IPv4-style netmask — surfacing during `vagrant up`/`reload` when the NetworkManager guest capability renders the device profile.

Common situations: Typos in Vagrantfile network stanzas; templates interpolating empty or wrong values into ip/netmask; IPv6 examples copied with IPv4 masks.

Related errors

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