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

You requested to remove the box '%{name}'. This box has mult

Error message

You requested to remove the box '%{name}'. This box has multiple
versions. You must explicitly specify which version you want to
remove with the `--box-version` flag or specify the `--all` flag
to remove all versions. The available versions for this box are:

%{versions}

What it means

Errors::BoxRemoveMultiVersion is raised when the named box has multiple versions installed, the user passed no --box-version, and --all was not requested. Vagrant refuses to guess which version to delete and prints every installed version.

Source

Thrown at lib/vagrant/action/builtin/box_remove.rb:43

          box_info = Util::HashWithIndifferentAccess.new
          env[:box_collection].all.each do |name, version, provider, architecture|
            next if name != box_name
            box_info[version] ||= Util::HashWithIndifferentAccess.new
            box_info[version][provider] ||= []
            box_info[version][provider] << architecture
          end

          # If there's no box info, then the box doesn't exist here
          if box_info.empty?
            raise Errors::BoxRemoveNotFound, name: box_name
          end

          # Filtering only matters if not removing all versions
          if !box_remove_all_versions
            # If no version was provided, and not removing all versions,
            # only allow one version to proceed
            if !box_version && box_info.size > 1
              raise Errors::BoxRemoveMultiVersion,
                name: box_name,
                versions: box_info.keys.sort.map { |k| " * #{k}" }.join("\n")
            end

            # If a version was provided, make sure it exists
            if box_version
              if !box_info.keys.include?(box_version)
                raise Errors::BoxRemoveVersionNotFound,
                  name: box_name,
                  version: box_version,
                  versions: box_info.keys.sort.map { |k| " * #{k}" }.join("\n")
              else
                box_info.delete_if { |k, _| k != box_version }
              end
            end

            # Only a single version remains
            box_version = box_info.keys.first

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Pick a version from the error's list: vagrant box remove NAME --box-version X.Y.Z.
  2. Remove every version at once: vagrant box remove NAME --all.
  3. Run 'vagrant box list' first to see the layout when scripting.

Example fix

# before
vagrant box remove ubuntu/jammy64   # 3 versions installed -> BoxRemoveMultiVersion

# after (one version)
vagrant box remove ubuntu/jammy64 --box-version 202303.0.0

# after (all versions)
vagrant box remove ubuntu/jammy64 --all
Defensive patterns

Strategy: validation

Validate before calling

versions = env.box_collection.all
  .select { |n, *, | n == box_name }.map { |_, v, *, | v }.uniq
if versions.size > 1
  # choose explicitly instead of letting vagrant prompt/raise
  remove(box_name, box_version: versions.sort.last)
end

Type guard

def single_version_box?(collection, name)
  collection.all.count { |n, *, | n == name && true } <= 1 ||
    collection.all.select { |n, *, | n == name }.map { |_, v, *, | v }.uniq.size == 1
end

Try / catch

begin
  env.cli("box", "remove", name)
rescue Vagrant::Errors::BoxRemoveMultiVersion => e
  # e.extra_data[:versions] is a pre-formatted ' * x.y.z' list
  chosen = e.extra_data[:versions].lines.first.strip.sub("* ", "")
  env.cli("box", "remove", name, "--box-version", chosen)
end

Prevention

When it happens

Trigger: box_remove_all_versions is falsy, box_version is nil, and box_info.size > 1 after the collection scan for box_name; the raise carries name and versions formatted as ' * version' lines.

Common situations: Long-lived workstations accumulating several versions of the same box; 'vagrant box remove ubuntu/jammy64' after box updates left old versions behind; cleanup scripts that assume a single version.

Related errors

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