hashicorp/vagrant · error · VagrantPlugins::DockerProvider::Errors::NetworkAddressInvalid

The configured network address is not valid within the confi

Error message

The configured network address is not valid within the configured
subnet of the defined network. Please update the network settings
and try again.

  Configured address: %{address}
  Network name:       %{network_name}

What it means

When a docker network definition resolves to an existing named network, validate_network_configuration! requires the configured static IP to belong to that network: driver.network_containing_address(ip) must return the same network name. An IP outside the network's subnet raises NetworkAddressInvalid with the address and network name.

Source

Thrown at plugins/providers/docker/action/prepare_networks.rb:70

          if !env[:machine].provider.driver.existing_named_network?(network_name)
            raise Errors::NetworkNameUndefined,
              network_name: network_name
          end
          true
        end

        # Validates that the provided options are compatible with a
        # pre-existing network. Raises exceptions on invalid configurations
        #
        # @param [String] network_name Name of the network
        # @param [Hash] root_options Root networking options
        # @param [Hash] network_options Docker scoped networking options
        # @param [Driver] driver Docker driver
        # @return [Boolean]
        def validate_network_configuration!(network_name, root_options, network_options, driver)
          if root_options[:ip] &&
              driver.network_containing_address(root_options[:ip]) != network_name
            raise Errors::NetworkAddressInvalid,
              address: root_options[:ip],
              network_name: network_name
          end
          if network_options[:subnet] &&
              driver.network_containing_address(network_options[:subnet]) != network_name
            raise Errors::NetworkSubnetInvalid,
              subnet: network_options[:subnet],
              network_name: network_name
          end
          true
        end

        # Generate configuration for private network
        #
        # @param [Hash] root_options Root networking options
        # @param [Hash] net_options Docker scoped networking options
        # @param [Hash] env Local call env
        # @return [String, Hash] Network name and updated network_options

View on GitHub (pinned to 35f3160f4a)

Solutions

Read the network's real subnet with `docker network inspect mynet` and pick an IP inside it
Or delete and recreate the docker network with a subnet containing your desired IP
Or drop the name: option and set subnet via docker_network__subnet so Vagrant derives or creates a matching network

Example fix

# before
config.vm.network "private_network", name: "mynet", ip: "192.168.50.10"
# mynet is 10.9.8.0/24 -> NetworkAddressInvalid

# after
config.vm.network "private_network", name: "mynet", ip: "10.9.8.42"

Defensive patterns

Strategy: validation

Validate before calling

# verify the static ip falls inside the network's subnet before up
SUBNET=$(docker network inspect mynet --format '{{(index .IPAM.Config 0).Subnet}}')
ruby -ripaddr -e "abort 'ip outside subnet' unless IPAddr.new('#{SUBNET}').include?('10.9.8.42')"

Prevention

Derive static IPs from `docker network inspect` output, never from memory
Document each network's subnet next to its Vagrantfile definition
Re-validate IPs after recreating any docker network

When it happens

Trigger: config.vm.network "private_network", name: "mynet", ip: "192.168.50.10" while mynet's subnet is e.g. 10.9.8.0/24; or the docker network was recreated with a different subnet after the IP was chosen.

Common situations: Reusing IPs from another environment; subnet-mask mismatches (network is /25 but the IP was picked as if /24); stale notes about network ranges.

Related errors

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