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

The configured network subnet is not valid for the defined…

Error message

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

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

What it means

Companion check in validate_network_configuration!: when docker-scoped options carry :subnet, the docker network containing that subnet must be the same network Vagrant resolved (driver.network_containing_address(subnet) == network_name). A subnet that maps to a different existing network raises NetworkSubnetInvalid with the subnet and network name.

Solutions

  1. Align the docker_network__subnet value with the network's actual subnet (`docker network inspect`)
  2. Remove the subnet override and let Vagrant derive addressing from the existing network
  3. Recreate the docker network with the desired subnet, then run vagrant up again

Example fix

# before
config.vm.network "private_network", name: "mynet",
  docker_network__subnet: "192.168.50.0/24"
# mynet is 10.9.8.0/24 -> NetworkSubnetInvalid

# after
config.vm.network "private_network", name: "mynet",
  docker_network__subnet: "10.9.8.0/24"
Defensive patterns

Strategy: validation

Validate before calling

# confirm the override subnet matches the network before up
ACTUAL=$(docker network inspect mynet --format '{{(index .IPAM.Config 0).Subnet}}')
[ "$ACTUAL" = "10.9.8.0/24" ] || echo "override subnet mismatch: network is $ACTUAL"

Prevention

When it happens

Trigger: Setting a subnet through docker_network__* scoped options that conflicts with the existing named docker network being reused - e.g. docker_network__subnet: "192.168.50.0/24" while the named network is 10.9.8.0/24.

Common situations: Stale per-provider subnet overrides after the shared docker network was recreated with a new range; copy-pasted overrides between projects with different ranges.

Related errors

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

Appendix: source

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

        # 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
        def process_private_network(root_options, network_options, env)
          if root_options[:name] && validate_network_name!(root_options[:name], env)
            network_name = root_options[:name]
          end

          if root_options[:type].to_s == "dhcp"

View on GitHub (pinned to 35f3160f4a)