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

Invalid option given for docker network for guest "%{contain

Error message

Invalid option given for docker network for guest "%{container}". Must specify either
a `subnet` or use `type: "dhcp"`.

What it means

A guard in PrepareNetworks#call: after dispatching each :public_network/:private_network entry to its processor, an entry whose result carries no network name is rejected with NetworkInvalidOption. The message states the contract - the network entry must pin addressing via a subnet or be marked type: "dhcp" (an ip: or name: also gives processing enough to derive a name).

Source

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

              env[:ui].info(I18n.t("docker_provider.network_create"))
              machine.config.vm.networks.each_with_index do |net_info, net_idx|
                type, options = net_info
                network_options = scoped_hash_override(options, :docker_network)
                network_options.delete_if{|k,_| options.key?(k)}

                case type
                when :public_network
                  network_name, network_options = process_public_network(
                    options, network_options, env)
                when :private_network
                  network_name, network_options = process_private_network(
                    options, network_options, env)
                else
                  next # unsupported type so ignore
                end

                if !network_name
                  raise Errors::NetworkInvalidOption, container: machine.name
                end

                if !machine.provider.driver.existing_named_network?(network_name)
                  @logger.debug("Creating network #{network_name}")
                  cli_opts = generate_create_cli_arguments(network_options)
                  machine.provider.driver.create_network(network_name, cli_opts)
                else
                  @logger.debug("Network #{network_name} already created")
                  validate_network_configuration!(network_name, options, network_options, machine.provider.driver)
                end
                connections[net_idx] = network_name
              end
            end
          end

          env[:docker_connects] = connections
          @app.call(env)
        end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Mark DHCP explicitly: config.vm.network "private_network", type: "dhcp"
2. Or supply addressing: ip: "172.20.0.10" or subnet: "172.20.0.0/24"
3. Update Vagrant - current code defaults nameless DHCP networks to the shared "vagrant_network"
4. Remove scoped overrides that delete ip/subnet/type options

Example fix

# before
config.vm.network "private_network"

# after
config.vm.network "private_network", type: "dhcp"
# or
config.vm.network "private_network", subnet: "172.20.0.0/24"

# quick lint: every docker-bound network needs ip, subnet, name, or dhcp
machine.config.vm.networks.each do |type, opts|
  next unless [:private_network, :public_network].include?(type)
  ok = opts[:ip] || opts[:subnet] || opts[:name] || opts[:type].to_s == "dhcp"
  warn "network lacks addressing: #{opts.inspect}" unless ok
end

When it happens

Trigger: vm.network entries whose option combination yields no network name after processing: in older Vagrant releases a type: "dhcp" network without ip/subnet fell through to this guard, and docker_network/docker_connect scoped overrides can strip ip/subnet/type until nothing usable remains.

Common situations: Copying VirtualBox-style bare `config.vm.network "private_network"` (DHCH implied there, not for docker) into a Docker-provider machine; hand-pruning network options while debugging.

Related errors

• There are errors in the configuration of this machine. Pleas
• The Docker provider is unable to connect the container to th
• The Docker provider was unable to configure networking using
• The configured network address is not valid within the confi
• The configured network subnet is not valid for the defined n

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