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

The box you attempted to add doesn't match the provider you

Error message

The box you attempted to add doesn't match the provider you specified.

Provider expected: %{expected}
Provider of box: %{actual}

What it means

BoxProviderDoesntMatch is raised in BoxCollection#add (lib/vagrant/box_collection.rb:151) after unpacking: the freshly extracted box's metadata.json declares provider X, but the caller requested a providers list that does not include X. Vagrant refuses to register the box under a provider it is not built for.

Source

Thrown at lib/vagrant/box_collection.rb:151

          end

          # We re-wrap ourselves in the safety net in case we upgraded.
          # If we didn't upgrade, then this is still safe because the
          # helper will only delete the directory if it exists
          with_temp_dir(temp_dir) do |final_temp_dir|
            # Get an instance of the box we just added before it is finalized
            # in the system so we can inspect and use its metadata.
            box = Box.new(name, nil, version, final_temp_dir)

            # Get the provider, since we'll need that to at the least add it
            # to the system or check that it matches what is given to us.
            box_provider = box.metadata["provider"]

            if providers
              found = providers.find { |p| p.to_sym == box_provider.to_sym }
              if !found
                @logger.error("Added box provider doesnt match expected: #{log_provider}")
                raise Errors::BoxProviderDoesntMatch,
                  expected: log_provider, actual: box_provider
              end
            else
              # Verify the box doesn't already exist
              check_box_exists.call([box_provider], architecture)
            end

            # We weren't given a provider, so store this one.
            provider = box_provider.to_sym

            # Create the directory for this box, not including the provider
            root_box_dir = @directory.join(dir_name(name))
            box_dir = root_box_dir.join(version)
            box_dir.mkpath
            @logger.debug("Box directory: #{box_dir}")

            # This is the final directory we'll move it to
            if architecture

View on GitHub (pinned to 35f3160f4a)

Solutions

Add with the provider the box actually declares: 'vagrant box add my.box --provider vmware_desktop'
Or download the correct artifact for your provider from the catalog and add that file
Check the box's declared provider first: 'bsdtar -xOf my.box ./metadata.json' (path may be 'metadata.json' at archive root)

Example fix

# before
vagrant box add ./mybox.box --provider virtualbox   # box is actually vmware_desktop

# after
vagrant box add ./mybox.box --provider vmware_desktop
# or fetch the virtualbox build from the catalog instead

Defensive patterns

Strategy: validation

Validate before calling

require 'json'
require 'open3'
out, = Open3.capture2('bsdtar', '-xOf', box_path.to_s, 'metadata.json')
declared = JSON.parse(out)['provider']
raise "box is #{declared}, not #{wanted}" unless declared == wanted

Prevention

Fetch provider-specific artifacts from catalog URLs instead of renaming local .box files
In CI, assert the box's declared provider matches the Vagrantfile provider before 'vagrant up'

When it happens

Trigger: 'vagrant box add my.box --provider virtualbox' where the unpacked metadata.json says "provider": "vmware_desktop": providers.find { |p| p.to_sym == box_provider.to_sym } returns nil and the error is raised with expected vs actual. Also occurs when Vagrantfile's provider and the box source disagree.

Common situations: Downloading a VMware/Hyper-V/QEMU build while the Vagrantfile or CLI targets VirtualBox; multi-provider catalogs where the wrong artifact link was grabbed; renaming a .box does not change its true provider.

Related errors

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