{"record":{"id":"98759b7db0ddb3f0","repo":"hashicorp/vagrant","slug":"vagrant-cannot-forward-the-specified-ports-on-this","errorCode":null,"errorMessage":"Vagrant cannot forward the specified ports on this VM, since they\nwould collide with some other application that is already listening\non these ports. The forwarded port to %{host_port} is already in use\non the host machine.\n\nTo fix this, modify your current project's Vagrantfile to use another\nport. Example, where '1234' would be replaced by a unique host port:\n\n  config.vm.network :forwarded_port, guest: %{guest_port}, host: 1234\n\nSometimes, Vagrant will attempt to auto-correct this for you. In this\ncase, Vagrant was unable to. This is usually because the guest machine\nis in a state which doesn't allow modifying port forwarding. You could\ntry 'vagrant reload' (equivalent of running a halt followed by an up)\nso vagrant can attempt to auto-correct this upon booting. Be warned\nthat any unsaved work might be lost.","messagePattern":"Vagrant cannot forward the specified ports on this VM, since they\nwould collide with some other application that is already listening\non these ports\\. The forwarded port to %\\{host_port\\} is already in use\non the host machine\\.\n\nTo fix this, modify your current project's Vagrantfile to use another\nport\\. Example, where '1234' would be replaced by a unique host port:\n\n  config\\.vm\\.network :forwarded_port, guest: %\\{guest_port\\}, host: 1234\n\nSometimes, Vagrant will attempt to auto-correct this for you\\. In this\ncase, Vagrant was unable to\\. This is usually because the guest machine\nis in a state which doesn't allow modifying port forwarding\\. You could\ntry 'vagrant reload' \\(equivalent of running a halt followed by an up\\)\nso vagrant can attempt to auto-correct this upon booting\\. Be warned\nthat any unsaved work might be lost\\.","errorType":"exception","errorClass":"Vagrant::Errors::ForwardPortCollision","httpStatus":null,"severity":"error","filePath":"lib/vagrant/action/builtin/handle_forwarded_port_collisions.rb","lineNumber":131,"sourceCode":"            if options[:protocol] && options[:protocol] != \"tcp\"\n              @logger.debug(\"Skipping #{host_port} because UDP protocol.\")\n              next\n            end\n\n            if remap[host_port]\n              remap_port = remap[host_port]\n              @logger.debug(\"Remap port override: #{host_port} => #{remap_port}\")\n              host_port = remap_port\n            end\n\n            # If the port is open (listening for TCP connections)\n            in_use = is_forwarded_already(extra_in_use, host_port, host_ip) ||\n              call_port_checker(port_checker, host_ip, host_port) ||\n              lease_check(host_ip, host_port)\n\n            if in_use\n              if !repair || !options[:auto_correct]\n                raise Errors::ForwardPortCollision,\n                  guest_port: guest_port.to_s,\n                  host_port:  host_port.to_s\n              end\n\n              @logger.info(\"Attempting to repair FP collision: #{host_port}\")\n\n              repaired_port = nil\n              while !usable_ports.empty?\n                # Attempt to repair the forwarded port\n                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...\")","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/hashicorp/vagrant/blob/35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5/lib/vagrant/action/builtin/handle_forwarded_port_collisions.rb#L113-L149","documentation":"The handle_forwarded_port_collisions middleware checks each forwarded host port against ports already forwarded within this environment, an external port checker, and DHCP lease reservations. If the port is in use and repair is impossible (auto_correct not enabled for this port, or `repair` mode off), it raises ForwardPortCollision naming the colliding host port.","triggerScenarios":"`vagrant up`/`vagrant reload` with a `config.vm.network \"forwarded_port\", guest: G, host: H` where H is already listening on the host (another VM, Docker container, local dev server) and the port lacks `auto_correct: true` (lib/vagrant/action/builtin/handle_forwarded_port_collisions.rb:126-134).","commonSituations":"Several Vagrant projects competing for the default SSH port 2222; a local web server already on 8080; Docker publishing the same port; the message's auto-correct path failing because the guest is in a state that does not allow re-configuring forwarding (then `vagrant reload` lets it retry at boot).","solutions":["Free the port: find the listener with `lsof -nP -iTCP:HOST_PORT -sTCP:LISTEN` (or `netstat -ano | findstr :HOST_PORT` on Windows) and stop it.","Or change to a unique host port in the Vagrantfile (`host: 18080`).","Or opt into auto-correction: add `auto_correct: true` to that forwarded_port declaration so Vagrant picks a free port from the correction range.","If auto-correct was already on but failed because the machine was running, `vagrant reload` lets Vagrant repair the collision at boot."],"exampleFix":"# before\nconfig.vm.network \"forwarded_port\", guest: 80, host: 8080  # 8080 already used on host\n\n# after\nconfig.vm.network \"forwarded_port\", guest: 80, host: 18080\n# or let Vagrant pick a free host port:\nconfig.vm.network \"forwarded_port\", guest: 80, host: 8080, auto_correct: true","handlingStrategy":"validation","validationCode":"# Ruby: assert the host port is free before `vagrant up`\nrequire \"socket\"\ndef port_free?(ip, port)\n  s = TCPServer.new(ip, port)\n  s.close\n  true\nrescue Errno::EADDRINUSE, Errno::EACCES\n  false\nend\nabort \"host port 8080 busy\" unless port_free?(\"0.0.0.0\", 8080)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Add `auto_correct: true` to forwarded_port entries that may race with other services.","In multi-project setups, allocate disjoint host-port ranges per project instead of reusing 8080/2222/3306.","Check listeners (`lsof -nP -iTCP:PORT -sTCP:LISTEN`) before upping when a port must be deterministic (e.g. for browser access)."],"tags":["vagrant","networking","port-forwarding","ports"],"backgroundTag":"port-already-in-use","analyzedSha":"35f3160f4ad6edc3a9f3aa9570adfc1a4d73aaa5","analyzedAt":"2026-08-21T13:34:32.514Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}