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

The adapter to attach a forwarded port to was not found. Ple

Error message

The adapter to attach a forwarded port to was not found. Please
verify that the given adapter is setup on the machine as a NAT
interface.

Host port: %{host}
Guest port: %{guest}
Adapter: %{adapter}

What it means

Before creating a NAT port-forward rule, the ForwardPorts action looks up the VM's network adapters (read_network_interfaces) and requires an entry at the forwarded port's adapter number. If interfaces[fp.adapter] is nil it raises ForwardPortAdapterNotFound, because VBoxManage would fail attaching the rule to a nonexistent NIC.

Source

Thrown at plugins/providers/virtualbox/action/forward_ports.rb:58

          interfaces = @env[:machine].provider.driver.read_network_interfaces

          @env[:forwarded_ports].each do |fp|
            message_attributes = {
              adapter: fp.adapter,
              guest_port: fp.guest_port,
              host_port: fp.host_port
            }

            # Assuming the only reason to establish port forwarding is
            # because the VM is using Virtualbox NAT networking. Host-only
            # bridged networking don't require port-forwarding and establishing
            # forwarded ports on these attachment types has uncertain behaviour.
            @env[:ui].detail(I18n.t("vagrant.actions.vm.forward_ports.forwarding_entry",
                                    **message_attributes))

            # Verify we have the network interface to attach to
            if !interfaces[fp.adapter]
              raise Vagrant::Errors::ForwardPortAdapterNotFound,
                adapter: fp.adapter.to_s,
                guest: fp.guest_port.to_s,
                host: fp.host_port.to_s
            end

            # Port forwarding requires the network interface to be a NAT interface,
            # so verify that that is the case.
            if interfaces[fp.adapter][:type] != :nat
              @env[:ui].detail(I18n.t("vagrant.actions.vm.forward_ports.non_nat",
                                    **message_attributes))
              next
            end

            # Add the options to the ports array to send to the driver later
            ports << {
              adapter:   fp.adapter,
              guestip:   fp.guest_ip,
              guestport: fp.guest_port,

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Remove the `adapter:` option from the forwarded_port definition and let Vagrant pick the default (0/1)
2. Ensure a network actually exists on that index, e.g. add `config.vm.network 'private_network', ip: ...` so adapter 2 exists before pinning adapter: 2
3. Check current NICs: `VBoxManage showvminfo <name> | grep -i nic` and align adapter numbers with what exists
4. Remove customize blocks that set '--nicN' to none/empty while forwarding ports on that index

Example fix

# Vagrantfile - before:
config.vm.network 'forwarded_port', guest: 80, host: 8080, adapter: 2  # VM has 1 NIC

# after (option A - drop the pin):
config.vm.network 'forwarded_port', guest: 80, host: 8080
# after (option B - create the adapter):
config.vm.network 'private_network', ip: '192.168.56.10'
config.vm.network 'forwarded_port', guest: 80, host: 8080, adapter: 2

# before up, reconcile forwarded_port adapter indexes with real NICs
nics = `VBoxManage showvminfo <name> --machinereadable`.scan(/^nic(\d+)="(?!none)/).map { |n| n.first.to_i }
ports = [{ host: 8080, guest: 80, adapter: 2 }]
bad = ports.select { |p| p[:adapter] && !nics.include?(p[:adapter]) }
abort "adapter #{bad.first[:adapter]} missing on VM" unless bad.empty?

begin
  env.cli('up')
rescue Vagrant::Errors::ForwardPortAdapterNotFound => e
  d = e.extra_data
  warn "No NIC #{d[:adapter]} for #{d[:host]}->#{d[:guest]}; drop `adapter:` or add a network on that index"
end

When it happens

Trigger: A forwarded-port definition with `adapter:` set to an index the VM does not have — e.g. `config.vm.network 'forwarded_port', guest: 80, host: 8080, adapter: 2` on a VM with only one NIC; or custom `config.vm.customize ['modifyvm', :id, '--nic2', 'none']` style tweaks removing the adapter.

Common situations: Copy-pasted Vagrantfiles that pin adapter numbers; boxes whose base OVF defines fewer NICs than expected; customizations that disable NICs; port-forward blocks inherited from another project with more networks defined.

Related errors

• No synced folder implementation is available for your synced
• The guest machine entered an invalid state while waiting for
• The snapshot name `%{snapshot_name}` was not found for the v
• The snapshot name `%{snapshot_name}` was not found for the v
• The checksum of the downloaded provider '%{provider}' did no

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