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

The box failed to unpackage properly. Please verify that the

Error message

The box failed to unpackage properly. Please verify that the box file you're trying to add is not corrupted and that enough disk space is available and then try again. The output from attempting to unpackage (if any):

%{output}

What it means

BoxUnpackageFailure is raised in BoxCollection#add (lib/vagrant/box_collection.rb:125) when the bsdtar extraction of the box archive into the temp directory exits non-zero. The error embeds bsdtar's stderr so you can see why the unpack failed; classic causes are a corrupt/non-archive file or insufficient disk space.

Source

Thrown at lib/vagrant/box_collection.rb:125

      with_collection_lock do
        log_provider = providers ? providers.join(", ") : "any provider"
        @logger.debug("Adding box: #{name} (#{log_provider} - #{architecture.inspect}) from #{path}")

        # Verify the box doesn't exist early if we're given a provider. This
        # can potentially speed things up considerably since we don't need
        # to unpack any files.
        check_box_exists.call(providers, architecture) if providers

        # Create a temporary directory since we're not sure at this point if
        # the box we're unpackaging already exists (if no provider was given)
        with_temp_dir do |temp_dir|
          # Extract the box into a temporary directory.
          @logger.debug("Unpacking box into temporary directory: #{temp_dir}")
          result = Util::Subprocess.execute(
            "bsdtar", "--no-same-owner", "--no-same-permissions", "-v", "-x", "-m", "-S", "-s", "|\\\\\|/|", "-C", temp_dir.to_s, "-f", path.to_s)
          if result.exit_code != 0
            raise Errors::BoxUnpackageFailure,
              output: result.stderr.to_s
          end

          # If we get a V1 box, we want to update it in place
          if v1_box?(temp_dir)
            @logger.debug("Added box is a V1 box. Upgrading in place.")
            temp_dir = v1_upgrade(temp_dir)
          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

View on GitHub (pinned to 35f3160f4a)

Solutions

  1. Verify the archive actually lists: 'bsdtar -tf ./mybox.box' (or 'tar tzf'); if it errors, the file is not a valid box archive — re-download
  2. Check free space on TMPDIR and the boxes dir: 'df -h /tmp ~/.vagrant.d'
  3. Compare a checksum (sha256sum) of the downloaded file against the publisher's checksum before re-adding
Defensive patterns

Strategy: validation

Validate before calling

result = Vagrant::Util::Subprocess.execute('bsdtar', '-tf', box_path.to_s)
raise 'not a valid box archive' unless result.exit_code == 0

Prevention

When it happens

Trigger: Util::Subprocess.execute('bsdtar', '--no-same-owner', ..., '-C', temp_dir, '-f', path) returns exit_code != 0 — the 'box' file is not a readable tar/zip (HTML error page, truncated download), the archive is corrupt, or the temp volume (TMPDIR) is full.

Common situations: Downloaded .box through a proxy that saved an HTML error page; scp/FTP transfer in binary mode not used; /tmp or VAGRANT_HOME on a full disk; file extension correct but content mangled.

Related errors

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