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

The configured network subnet is not valid for the defined n

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.

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)

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"

# 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"

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

• The configured network address is not valid within the confi
• The Docker provider is unable to connect the container to th
• The Docker provider was unable to configure networking using
• Invalid option given for docker network for guest "%{contain
• NFS requires a host-only network to be created. Please add a

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