hashicorp/vagrant · error · VagrantPlugins::HyperV::Errors::BoxInvalid

The box you're using with the Hyper-V provider ('%{name}') i

Error message

The box you're using with the Hyper-V provider ('%{name}')
is invalid. A Hyper-V box should contain both a
"Virtual Machines" and a "Virtual Hard Disks" folder that are
created as part of exporting a Hyper-V machine.

Within these directories, Vagrant expects to find the
virtual machine configuration as well as the root hard disk.

The box you're attempting to use is missing one or both of
these directories or does not contain the files expected. Verify
that you added the correct box. If this problem persists,
please contact the creator of the box for assistance.

What it means

The Hyper-V Import action expects the unpacked box directory to contain the two folders a Hyper-V export produces: 'Virtual Machines' and 'Virtual Hard Disks'. If either is missing, BoxInvalid is raised before any .xml/.vmcx config lookup happens - the artifact simply is not a valid Hyper-V box.

Source

Thrown at plugins/providers/hyperv/action/import.rb:25

module VagrantPlugins
  module HyperV
    module Action
      class Import

        VALID_HD_EXTENSIONS = [".vhd".freeze, ".vhdx".freeze].freeze

        def initialize(app, env)
          @app = app
          @logger = Log4r::Logger.new("vagrant::hyperv::import")
        end

        def call(env)
          vm_dir = env[:machine].box.directory.join("Virtual Machines")
          hd_dir = env[:machine].box.directory.join("Virtual Hard Disks")

          if !vm_dir.directory? || !hd_dir.directory?
            @logger.error("Required virtual machine directory not found!")
            raise Errors::BoxInvalid, name: env[:machine].name
          end

          valid_config_ext = [".xml"]
          if env[:machine].provider.driver.has_vmcx_support?
            valid_config_ext << ".vmcx"
          end

          config_path = nil
          vm_dir.each_child do |file|
            if valid_config_ext.include?(file.extname.downcase)
              config_path = file
              break
            end
          end

          if !config_path
            @logger.error("Failed to locate box configuration path")
            raise Errors::BoxInvalid, name: env[:machine].name

View on GitHub (pinned to 35f3160f4a)

Solutions

1. Inspect the artifact: `tar -tf box.box` must list 'Virtual Machines/' and 'Virtual Hard Disks/'
2. Rebuild properly: export from a working Hyper-V VM, or `vagrant package` on a Hyper-V machine, then `vagrant box add` the result
3. Remove the broken copy (`vagrant box remove <name>`) before re-adding the fixed artifact
4. Report broken published boxes to their maintainer

Example fix

# before: hand-made box
tar -cf my.box metadata.json init.tar.gz   # -> BoxInvalid on import

# after: package from a real Hyper-V VM
vagrant halt && vagrant package --output my.box
vagrant box add my-box my.box

tar -tf box.box | grep -q 'Virtual Machines/' \
  && tar -tf box.box | grep -q 'Virtual Hard Disks/' \
  || echo 'not a valid Hyper-V box'
vagrant box add my-box box.box

When it happens

Trigger: `vagrant up --provider=hyperv` with a box built without a Hyper-V export layout: hand-assembled tarballs, boxes repackaged from other providers, or corrupted/partial extraction into the box directory.

Common situations: Manually crafted boxes; repackaging a VirtualBox box for Hyper-V by renaming; truncated downloads or disk-full extraction during `vagrant box add`.

Related errors

• cloud-init is not found. Please ensure that cloud-init is in
• The specified file '%{filename}' to save the package as alre
• The specified output is a directory. Please specify a path i
• The information file that you've attempted to include doesn'
• Package include file doesn't exist: %{file}

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