hashicorp/vagrant · info

Warning: When using a remote Docker host, forwarded ports wi

Error message

Warning: When using a remote Docker host, forwarded ports will NOT be
immediately available on your machine. They will still be forwarded on
the remote machine, however, so if you have a way to access the remote
machine, then you should be able to access those ports there. This is
not an error, it is only an informational message.

What it means

When the Docker provider runs containers inside a host VM or against a remote Docker machine (provider.host_vm? true, e.g. macOS/Windows without native Docker), forwarded ports bind on that host VM, not on your physical machine. With any forwarded_port network defined, this informational warning states the ports are reachable only via the remote/host-VM machine.

Source

Thrown at plugins/providers/docker/action/host_machine_port_warning.rb:21

module VagrantPlugins
  module DockerProvider
    module Action
      class HostMachinePortWarning
        def initialize(app, env)
          @app = app
        end

        def call(env)
          if !env[:machine].provider.host_vm?
            return @app.call(env)
          end

          # If we have forwarded ports, then notify the user that they
          # won't be immediately available unless a private network
          # is created.
          if has_forwarded_ports?(env[:machine])
            env[:machine].ui.warn(I18n.t(
              "docker_provider.host_machine_forwarded_ports"))
          end

          @app.call(env)
        end

        protected

        def has_forwarded_ports?(machine)
          machine.config.vm.networks.each do |type, _|
            return true if type == :forwarded_port
          end

          false
        end
      end
    end
  end

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Reach the port on the host VM/remote machine (its IP), or tunnel to it: `vagrant ssh -- -L 8080:localhost:8080`
2. Add a private_network so the guest gets an IP you can contact directly
3. Install native Docker (Docker Desktop or engine) and drop the host VM so ports bind on your machine

Example fix

# before
config.vm.network "forwarded_port", guest: 80, host: 8080  # binds on host VM only
# after
config.vm.network "private_network", ip: "192.168.56.10"  # reachable directly

# Detect the situation before up: docker provider with a host VM
vagrant config docker.host_vm 2>/dev/null || echo "check provider.host_vm? in a trigger"

ports_bind_locally = ->(machine) { !machine.provider.host_vm? }

When it happens

Trigger: Docker provider with a host VM or remote Docker host plus `config.vm.network "forwarded_port", guest: 80, host: 8080` in the Vagrantfile, during vagrant up; has_forwarded_ports? finds the network and the warn fires.

Common situations: macOS/Windows users with a boot2docker-style default VM; remote docker-machine style hosts; expecting localhost:8080 to serve the container.

Related errors

• The Docker provider was able to bring up the host VM success
• A Docker command executed by Vagrant didn't complete success
• The configured host VM Vagrantfile could not be found. Pleas
• Multiple URLs for a box can't be specified when adding versi
• The Docker provider is unable to connect the container to th

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