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

The provider '%{provider}' could not be found, but was reque

Error message

The provider '%{provider}' could not be found, but was requested to
back the machine '%{machine}'. Please use a provider that exists.

Did you mean '%{suggestion}'?

What it means

Raised by VagrantFile#machine_config when the requested provider string does not exactly match a registered provider plugin, but a case-insensitive match does exist in the provider registry. Providers are registered as lowercase symbols (virtualbox, hyperv, ...), so `--provider VirtualBox` fails the exact lookup and this error offers the downcased name as a suggestion.

Source

Thrown at lib/vagrant/vagrantfile.rb:141

          name: name, provider: provider
      end

      provider_plugin  = nil
      provider_cls     = nil
      provider_options = {}
      box_formats      = nil
      if provider != nil
        provider_plugin  = Vagrant.plugin("2").manager.providers[provider]
        if !provider_plugin && validate_provider
          providers  = Vagrant.plugin("2").manager.providers.to_hash.keys
          if providers
            providers_str = providers.join(', ')
          else
            providers_str = "N/A"
          end

          if providers.include? provider.downcase
            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,

View on GitHub (pinned to 35f3160f4a)

Solutions

Use the suggestion printed in the message (the correct lowercase provider name)
Normalize provider strings to lowercase before passing them on the CLI or API
Quote the full flag value to avoid shell mangling: `--provider=virtualbox`

Example fix

# before
vagrant up --provider=VirtualBox

# after
vagrant up --provider=virtualbox

Defensive patterns

Strategy: type-guard

Validate before calling

# bash: normalize before invoking
PROVIDER="${PROVIDER,,}"   # bash 4+ lowercase
vagrant up --provider="$PROVIDER"

Type guard

# Ruby: exact-match a provider name after normalizing case
KNOWN = Vagrant.plugin('2').manager.providers.to_hash.keys.map(&:to_s)
def valid_provider?(name)
  KNOWN.include?(name.to_s.downcase)
end

Prevention

Always pass provider names lowercase on the CLI and in scripts
Downcase provider strings coming from user input or env vars before use
Use --provider=value quoting to avoid shell word-splitting surprises

When it happens

Trigger: `vagrant up --provider=VirtualBox`, `--provider Docker`, or API calls to machine_config/machine with a mixed-case provider string where the downcased name is registered in Vagrant.plugin("2").manager.providers.

Common situations: Scripts or documentation written with human-cased provider names; provider strings taken from user input or environment variables without normalization; copy-paste from marketing names (VMware Fusion vs vmware_desktop is a different error - that is a true not-found).

Related errors

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