{"record":{"id":"22710cd955bfabd5","repo":"hashicorp/vagrant","slug":"vagrant-found-a-port-collision-for-the-specified-p","errorCode":null,"errorMessage":"Vagrant found a port collision for the specified port and virtual machine.\nWhile this port was marked to be auto-corrected, the ports in the\nauto-correction range are all also used.\n\nVM: %{vm_name}\nForwarded port: %{guest_port} => %{host_port}","messagePattern":"Vagrant found a port collision for the specified port and virtual machine\\.\nWhile this port was marked to be auto-corrected, the ports in the\nauto-correction range are all also used\\.\n\nVM: %(.+?)\nForwarded port: %(.+?) => %(.+?)","errorType":"exception","errorClass":"Vagrant::Errors::ForwardPortAutolistEmpty","httpStatus":null,"severity":"error","filePath":"lib/vagrant/action/builtin/handle_forwarded_port_collisions.rb","lineNumber":159,"sourceCode":"                repaired_port = usable_ports.to_a.sort[0]\n                usable_ports.delete(repaired_port)\n\n                # If the port is in use, then we can't use this either...\n                in_use = is_forwarded_already(extra_in_use, repaired_port, host_ip) ||\n                  call_port_checker(port_checker, host_ip, repaired_port) ||\n                  lease_check(host_ip, repaired_port)\n                if in_use\n                  @logger.info(\"Repaired port also in use: #{repaired_port}. Trying another...\")\n                  next\n                end\n\n                # We have a port so break out\n                break\n              end\n\n              # If we have no usable ports then we can't repair\n              if !repaired_port && usable_ports.empty?\n                raise Errors::ForwardPortAutolistEmpty,\n                  vm_name:    env[:machine].name,\n                  guest_port: guest_port.to_s,\n                  host_port:  host_port.to_s\n              end\n\n              # Modify the args in place\n              options[:host] = repaired_port\n\n              @logger.info(\"Repaired FP collision: #{host_port} to #{repaired_port}\")\n\n              # Notify the user\n              env[:ui].info(I18n.t(\"vagrant.actions.vm.forward_ports.fixed_collision\",\n                                   host_port:  host_port.to_s,\n                                   guest_port: guest_port.to_s,\n                                   new_port:   repaired_port.to_s))\n            end\n          end\n        end","sourceCodeStart":141,"sourceCodeEnd":177,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/lib/vagrant/action/builtin/handle_forwarded_port_collisions.rb#L141-L177","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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."],"exampleFix":"# before (default 2200..2250 exhausted by parallel VMs)\nVagrant.configure(\"2\") do |config|\n  config.vm.network \"forwarded_port\", guest: 80, host: 8080, auto_correct: true\nend\n\n# after\nVagrant.configure(\"2\") do |config|\n  config.vm.usable_port_range = 2200..3999\n  config.vm.network \"forwarded_port\", guest: 80, host: 8080, auto_correct: true\nend","handlingStrategy":"validation","validationCode":"# Ruby: ensure the auto-correct range has free capacity before upping many VMs\nrequire \"socket\"\nfree = (2200..2250).count do |p|\n  begin\n    s = TCPServer.new(\"0.0.0.0\", p); s.close; true\n  rescue Errno::EADDRINUSE\n    false\n  end\nend\nputs \"#{free}/51 correction ports free\"; abort \"widen usable_port_range\" if free < 5","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["vagrant","port-forwarding","auto-correct","ports"],"backgroundTag":"port-already-in-use","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}