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

The provider '%{provider}' that was requested to back the ma

Error message

The provider '%{provider}' that was requested to back the machine
'%{machine}' is reporting that it isn't usable on this system. The
reason is shown below:

%{message}

What it means

Raised when the provider plugin is registered but its `usable?(true)` check raised - the provider itself reported it cannot run on this machine, and the original exception text is embedded as the message. This is an environment problem (missing hypervisor, unlicensed product, disabled feature), not a name-lookup problem.

Source

Thrown at lib/vagrant/vagrantfile.rb:159

            raise Errors::ProviderNotFoundSuggestion,
              machine: name, provider: provider,
              suggestion: provider.downcase, providers: providers_str
          end

          raise Errors::ProviderNotFound,
            machine: name, provider: provider, providers: providers_str
        end

        if validate_provider
          provider_cls     = provider_plugin[0]
          provider_options = provider_plugin[1]
          box_formats      = provider_options[:box_format] || provider

          # Test if the provider is usable or not
          begin
            provider_cls.usable?(true)
          rescue Errors::VagrantError => e
            raise Errors::ProviderNotUsable,
              machine: name.to_s,
              provider: provider.to_s,
              message: e.to_s
          end
        else
          box_formats = provider
        end
      end

      # Add the sub-machine configuration to the loader and keys
      vm_config_key = "#{object_id}_machine_#{name}"
      @loader.set(vm_config_key, sub_machine.config_procs)
      keys << vm_config_key

      # Load once so that we can get the proper box value
      config, config_warnings, config_errors = @loader.load(keys)

      # Track the original box so we know if we changed

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Read the embedded provider message - it states exactly what is missing (VBoxManage not found, license required, feature disabled)
2. Install or enable the provider runtime (VirtualBox, VMware plus license, Hyper-V feature, docker daemon)
3. Verify the binary works standalone before retrying (e.g. `VBoxManage --version`, `docker info`)
4. Check version-compatibility notes between your Vagrant release and the provider (e.g. VirtualBox 7.x support landed in newer Vagrant)

Example fix

# before: VirtualBox not installed
vagrant up --provider=virtualbox
# error: provider virtualbox not usable: The 'VBoxManage' command ... not found

# after
sudo apt-get install virtualbox-7.1   # or: brew install --cask virtualbox
vagrant up --provider=virtualbox

# bash: verify the provider runtime exists before vagrant up
case "$PROVIDER" in
  virtualbox) VBoxManage --version >/dev/null 2>&1 || { echo 'install VirtualBox first'; exit 1; } ;;
  docker)      docker info >/dev/null 2>&1 || { echo 'start the docker daemon'; exit 1; } ;;
esac

# Ruby: probe usability before loading machines
begin
  provider_cls.usable?(false)
rescue Vagrant::Errors::VagrantError => e
  abort "provider not usable: #{e.message}"
end

begin
  env.cli(%w(up))
rescue Vagrant::Errors::ProviderNotUsable => e
  warn "fix the provider runtime first: #{e.extra_data[:message]}"
  exit 1
end

When it happens

Trigger: `--provider=virtualbox` with VirtualBox missing or an unsupported version; `--provider=hyperv` with the Hyper-V Windows feature disabled; `--provider=vmware_desktop` without a valid VMware license; `--provider=docker` with no reachable docker daemon.

Common situations: Fresh CI machines or new laptops without the hypervisor installed; macOS/Windows updates disabling virtualization; VirtualBox upgraded to a version the installed Vagrant does not yet support; expired VMware plugin license.

Related errors

• Vagrant is unable to determine the location of this instance
• The provider '%{provider}' could not be found, but was reque
• You requested to remove the box '%{name}' version '%{version
• The clone environment hasn't been created yet. To clone from
• The box you attempted to add doesn't match the provider you

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