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

The Docker provider was unable to configure networking using

Error message

The Docker provider was unable to configure networking using the
provided network name `%{network_name}`. Please ensure the network
name is correct and exists, then try again.

What it means

validate_network_name! - used by process_private_network and process_public_network in the Docker provider's PrepareNetworks action - requires that a network referenced by name already exist in the docker engine (driver.existing_named_network? wraps `docker network ls`). A name the engine does not know raises NetworkNameUndefined.

Source

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

        end

        # @return [Array<Socket::Ifaddr>] interface list
        def list_interfaces
          Socket.getifaddrs.find_all do |i|
            !i.addr.nil? && i.addr.ip? && !i.addr.ipv4_loopback? &&
              !i.addr.ipv6_loopback? && !i.addr.ipv6_linklocal?
          end
        end

        # Validates that a network name exists. If it does not
        # exist, an exception is raised.
        #
        # @param [String] network_name Name of existing network
        # @param [Hash] env Local call env
        # @return [Boolean]
        def validate_network_name!(network_name, env)
          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],

View on GitHub (pinned to 35f3160f4a)

Solutions

List networks with `docker network ls` and fix the name: option to match exactly
Create the network before starting: docker network create --subnet 10.9.8.0/24 mynet
If using a remote daemon/docker context, confirm you are querying the engine that actually owns the network

Example fix

# before
config.vm.network "private_network", name: "my_net"  # typo; engine has "mynet"

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

Defensive patterns

Strategy: validation

Validate before calling

# ensure the named network exists (or create it) before vagrant up
docker network inspect mynet >/dev/null 2>&1 \
  || docker network create --subnet 10.9.8.0/24 mynet
vagrant up

Prevention

Create named networks as a provisioning step before `vagrant up`
Verify docker context/DOCKER_HOST when sharing Vagrantfiles across machines
Use exact names from `docker network ls`; avoid renaming networks out-of-band

When it happens

Trigger: config.vm.network "private_network", name: "mynet" (or the same via docker_network/docker_connect scoped overrides) when no docker network named mynet exists in the engine Vagrant talks to.

Common situations: Typos in network names; the network deleted out-of-band between ups; DOCKER_HOST or a docker context pointing at a different engine than the one holding the network.

Related errors

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