hashicorp/vagrant · error · Vagrant::Errors::ForwardPortAutolistEmpty

Vagrant found a port collision for the specified port and vi

Error message

Vagrant found a port collision for the specified port and virtual machine.
While this port was marked to be auto-corrected, the ports in the
auto-correction range are all also used.

VM: %{vm_name}
Forwarded port: %{guest_port} => %{host_port}

What it means

With auto_correct enabled, Vagrant tries to repair a port collision by walking the correction range (config.vm.usable_port_range, default 2200..2250) and taking the first free port. If every port in that range is also in use, usable_ports is exhausted with no repair made and ForwardPortAutolistEmpty is raised for that VM/port pair.

Source

Thrown at lib/vagrant/action/builtin/handle_forwarded_port_collisions.rb:159

                repaired_port = usable_ports.to_a.sort[0]
                usable_ports.delete(repaired_port)

                # If the port is in use, then we can't use this either...
                in_use = is_forwarded_already(extra_in_use, repaired_port, host_ip) ||
                  call_port_checker(port_checker, host_ip, repaired_port) ||
                  lease_check(host_ip, repaired_port)
                if in_use
                  @logger.info("Repaired port also in use: #{repaired_port}. Trying another...")
                  next
                end

                # We have a port so break out
                break
              end

              # If we have no usable ports then we can't repair
              if !repaired_port && usable_ports.empty?
                raise Errors::ForwardPortAutolistEmpty,
                  vm_name:    env[:machine].name,
                  guest_port: guest_port.to_s,
                  host_port:  host_port.to_s
              end

              # Modify the args in place
              options[:host] = repaired_port

              @logger.info("Repaired FP collision: #{host_port} to #{repaired_port}")

              # Notify the user
              env[:ui].info(I18n.t("vagrant.actions.vm.forward_ports.fixed_collision",
                                   host_port:  host_port.to_s,
                                   guest_port: guest_port.to_s,
                                   new_port:   repaired_port.to_s))
            end
          end
        end

View on GitHub (pinned to 35f3160f4a)

Solutions

Widen the correction range in your Vagrantfile: `config.vm.usable_port_range = 2200..3999` (or any range you know is free).
Free ports inside the current range (check with `lsof -nP -iTCP -sTCP:LISTEN | awk '$9 ~ /:22[0-9][0-9]/'`).
Reduce simultaneous VMs, or assign explicit unique host ports per machine instead of relying on auto-correct.

Example fix

# before (default 2200..2250 exhausted by parallel VMs)
Vagrant.configure("2") do |config|
  config.vm.network "forwarded_port", guest: 80, host: 8080, auto_correct: true
end

# after
Vagrant.configure("2") do |config|
  config.vm.usable_port_range = 2200..3999
  config.vm.network "forwarded_port", guest: 80, host: 8080, auto_correct: true
end

Defensive patterns

Strategy: validation

Validate before calling

# Ruby: ensure the auto-correct range has free capacity before upping many VMs
require "socket"
free = (2200..2250).count do |p|
  begin
    s = TCPServer.new("0.0.0.0", p); s.close; true
  rescue Errno::EADDRINUSE
    false
  end
end
puts "#{free}/51 correction ports free"; abort "widen usable_port_range" if free < 5

Prevention

Set an explicit, generously sized `config.vm.usable_port_range` in environments with many VMs or parallel CI.
Prefer explicit unique host ports over auto_correct when ports must be predictable.
Don't let other toolchains (Docker, other Vagrant projects) publish ports inside your correction range.

When it happens

Trigger: `vagrant up` with auto_correct: true where the original host port collides AND every port in the usable range (checked via port checker + lease check) is occupied (lib/vagrant/action/builtin/handle_forwarded_port_collisions.rb:136-161). Typical: ~51+ VMs brought up in parallel, other services squatting 2200-2250.

Common situations: Large multi-machine Vagrantfiles or parallel CI jobs exhausting the default 2200..2250 range; Docker/other Vagrant projects holding that range; host firewalls/agents binding wide port spans.

Related errors

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