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

The Docker provider is unable to connect the container to th

Error message

The Docker provider is unable to connect the container to the
defined network due to a missing network name. Please validate
your configuration and try again.

  Container: %{container}
  Network Number: %{index}

What it means

During `vagrant up`, the Docker provider runs PrepareNetworks, which computes/creates docker networks and stores their names in env[:docker_connects] keyed by network index; ConnectNetworks later reads connections[idx] to run `docker network connect`. If the entry for a private/public network index is missing, NetworkNameMissing is raised with the container name and index.

Source

Thrown at plugins/providers/docker/action/connect_networks.rb:57

          if machine.provider.host_vm?
            @logger.debug("Not setting up networks because docker host_vm is in use")
            return @app.call(env)
          end

          env[:ui].info(I18n.t("docker_provider.network_connect"))

          connections = env[:docker_connects] || {}

          machine.config.vm.networks.each_with_index do |args, idx|
            type, options = args
            next if type != :private_network && type != :public_network

            network_options = scoped_hash_override(options, :docker_connect)
            network_options.delete_if{|k,_| options.key?(k)}
            network_name = connections[idx]

            if !network_name
              raise Errors::NetworkNameMissing,
                index: idx,
                container: machine.name
            end

            @logger.debug("Connecting network #{network_name} to container guest #{machine.name}")
            if options[:ip] && options[:type] != "dhcp"
              if IPAddr.new(options[:ip]).ipv4?
                network_options[:ip] = options[:ip]
              else
                network_options[:ip6] = options[:ip]
              end
            end
            network_options[:alias] = options[:alias] if options[:alias]
            connect_opts = generate_connect_cli_arguments(network_options)
            machine.provider.driver.connect_network(network_name, machine.id, connect_opts)
          end

          @app.call(env)

View on GitHub (pinned to 35f3160f4a)

Solutions

Clean re-run so the full chain executes: `vagrant destroy -f && vagrant up`
Update Vagrant - fixes to the prepare/connect handoff ship in patch releases
If you build custom middleware, invoke the provider's built-in up chain instead of ConnectNetworks in isolation
Reproduce with VAGRANT_LOG=debug and look for 'Connecting network' entries to identify which index is missing

Defensive patterns

Strategy: validation

Validate before calling

# before invoking the docker provider's ConnectNetworks action
missing = machine.config.vm.networks.each_with_index.select do |(type, _), idx|
  [:private_network, :public_network].include?(type) && env[:docker_connects].to_h[idx].nil?
end
raise 'PrepareNetworks must populate env[:docker_connects] first' unless missing.empty?

Prevention

Prefer the provider's built-in up chain over hand-assembled middleware
Use destroy+up rather than resuming partially failed runs when custom networking is involved
Pin a known-good Vagrant version across the team so prepare and connect stay in sync

When it happens

Trigger: ConnectNetworks executing in an action env that PrepareNetworks never populated: custom middleware chains or plugins invoking the docker provider's connect action directly, an interrupted earlier prepare step, or any state where env[:docker_connects] is absent or lacks that index.

Common situations: Third-party tooling that reuses Docker provider actions outside the built-in up chain; a partially failed `vagrant up` followed by a partial re-run; version drift between the prepare and connect actions.

Related errors

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