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

The executable '%{file}' Vagrant is trying to run was not fo

Error message

The executable '%{file}' Vagrant is trying to run was not
found in the %PATH% variable. This is an error. Please verify
this software is installed and on the path.

What it means

Vagrant::Util::Subprocess#initialize resolves the command's first token via Which.which (skipped only when it is already an existing file path); if resolution fails on Windows it raises CommandUnavailableWindows with the executable name in %{file}. Every Vagrant shell-out (curl, ssh, rsync, powershell, ...) funnels through this check.

Source

Thrown at lib/vagrant/util/subprocess.rb:33

  module Util
    # Execute a command in a subprocess, gathering the results and
    # exit status.
    #
    # This class also allows you to read the data as it is outputted
    # from the subprocess in real time, by simply passing a block to
    # the execute method.
    class Subprocess
      # Convenience method for executing a method.
      def self.execute(*command, &block)
        new(*command).execute(&block)
      end

      def initialize(*command)
        @options = command.last.is_a?(Hash) ? command.pop : {}
        @command = command.dup
        @command[0] = Which.which(@command[0]) if !File.file?(@command[0])
        if !@command[0]
          raise Errors::CommandUnavailableWindows, file: command[0] if Platform.windows?
          raise Errors::CommandUnavailable, file: command[0]
        end

        @logger  = Log4r::Logger.new("vagrant::util::subprocess")
      end

      # @return [TrueClass, FalseClass] subprocess is currently running
      def running?
        !!(@process && @process.alive?)
      end

      # Stop the subprocess if running
      #
      # @return [TrueClass] FalseClass] true if process was running and stopped
      def stop
        if @process && @process.alive?
          @process.stop
          true

View on GitHub (pinned to 35f3160f4a)

Solutions

Install the executable named in %{file} on the Windows host
Add its directory to PATH and restart the shell/agent so Vagrant inherits it
Prefer absolute file paths as argv[0] in your own Subprocess calls (that path skips Which), and verify with `where <file>` in the same environment

Example fix

# before
> vagrant up   # CommandUnavailableWindows: 'rsync'

# after: install rsync (e.g. via Git for Windows), then
> setx PATH "%PATH%;C:\Program Files\Git\usr\bin"
> vagrant up

Defensive patterns

Strategy: validation

Validate before calling

require 'vagrant/util/which'

tool = 'rsync'
path = Vagrant::Util::Which.which(tool)
abort "#{tool} not on PATH; install it before continuing" unless path

Try / catch

begin
  Vagrant::Util::Subprocess.execute('rsync', '-a', src, dst)
rescue Vagrant::Errors::CommandUnavailableWindows => e
  abort "install #{e.extra_data[:file]} and ensure it is on PATH"
end

Prevention

Pre-install host tooling (rsync/ssh/tar) on Windows hosts
Which.which-check tools before long operations
Remember Subprocess resolves argv[0] via PATH unless it is an existing file path

When it happens

Trigger: Any Subprocess.execute('tool', ...) where the tool is not found on the Windows PATH: rsync synced folders without rsync.exe, missing ssh, provisioners referencing uninstalled utilities.

Common situations: Windows hosts missing extras Vagrant assumes (rsync from Git for Windows/cwRsync, ssh, tar); PATH differences between interactive and service contexts.

Related errors

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