hashicorp/vagrant · error · VagrantPlugins::CommandRDP::Errors::HostUnsupported

Vagrant doesn't support running an RDP client on your host O

Error message

Vagrant doesn't support running an RDP client on your host OS. If you wish for the OS you're running to support launching an RDP client, please contribute this functionality back into Vagrant. At the very least, open an issue on how it could be done and we can handle the integration.

What it means

`vagrant rdp` requires the HOST operating system to expose an `rdp_client` capability, which only some host platforms provide. The command checks `@env.host.capability?(:rdp_client)` before touching any machine and raises HostUnsupported when no host plugin registers the capability. This is a host-platform limitation, independent of the guest's state.

Source

Thrown at plugins/commands/rdp/command.rb:33

        opts = OptionParser.new do |o|
          o.banner = "Usage: vagrant rdp [options] [name|id] [-- extra args]"
        end

        # Parse out the extra args to send to the RDP client, which
        # is everything after the "--"
        split_index = @argv.index("--")
        if split_index
          options[:extra_args] = @argv.drop(split_index + 1)
          @argv                = @argv.take(split_index)
        end

        # Parse the options and return if we don't have any target.
        argv = parse_options(opts)
        return if !argv

        # Check if the host even supports RDP
        raise Errors::HostUnsupported if !@env.host.capability?(:rdp_client)

        # Execute RDP if we can
        with_target_vms(argv, single_target: true) do |machine|
          if !machine.communicate.ready?
            raise Vagrant::Errors::VMNotCreatedError
          end

          machine.ui.output(I18n.t("vagrant_rdp.detecting"))
          rdp_info = get_rdp_info(machine)
          raise Errors::RDPUndetected if !rdp_info

          # Extra arguments if we have any
          rdp_info[:extra_args] = options[:extra_args]

          machine.ui.detail(
            "Address: #{rdp_info[:host]}:#{rdp_info[:port]}")
          machine.ui.detail("Username: #{rdp_info[:username]}")

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Get the connection details and connect manually: `vagrant port --guest 3389` (or read the forwarded port) and use an RDP client such as xfreerdp or Remmina
2. Run the command from a host Vagrant supports for RDP (e.g. Windows or macOS with an available client)
3. Install or contribute a host plugin that implements the `rdp_client` capability for your platform

Example fix

# before (unsupported Linux host)
# vagrant rdp  ->  HostUnsupported

# after
# vagrant port --guest 3389        # e.g. prints 33389
# xfreerdp /v:127.0.0.1:33389 /u:vagrant

raise 'this host cannot launch an RDP client' unless env.host.capability?(:rdp_client)
env.host.capability(:rdp_client, rdp_info)

begin
  VagrantPlugins::CommandRDP::Command.new(argv, env).execute
rescue Vagrant::Errors::HostUnsupported
  # print connection info and let the user connect with a native RDP client
end

When it happens

Trigger: Running `vagrant rdp` on a Linux/BSD host whose detected host class implements no `rdp_client` capability; running inside a container, WSL, or headless CI session where host detection selects a generic host without RDP integration.

Common situations: Developers on Linux wanting to RDP into a Windows guest; CI pipelines that call `vagrant rdp` in containers; older Vagrant builds whose host detection differs from the current platform.

Related errors

• Vagrant cannot create an iso due to the host capability for
• Your host does not support PowerShell. A remote PowerShell c
• The provider '%{provider}' doesn't support automatic install
• RDP connection information for this machine could not be det
• This Vagrant environment has specified that it requires the

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