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

The guest does not provide extraction capability for the req

Error message

The guest does not provide extraction capability for the requested
compression type (`%{type}`). Try a different compression type or
upload without compression.

What it means

When compression is enabled, `vagrant upload` requires the GUEST to be able to unpack the chosen format: it checks the guest capability `decompress_tgz` or `decompress_zip`. UploadMissingExtractCapability fires when the guest's capability chain does not implement the decompress method matching the compression type. The upload never starts; this is a guest-support check.

Source

Thrown at plugins/commands/upload/command.rb:150

      #
      # @param [Vagrant::Machine] machine Vagrant guest machine
      # @param [Hash] options Command options
      def compression_setup!(machine, options)
        if !options[:compression_type]
          if machine.guest.capability_host_chain.first[0] == :windows
            options[:compression_type] = :zip
          else
            options[:compression_type] = :tgz
          end
        end
        if !VALID_COMPRESS_TYPES.include?(options[:compression_type])
          raise Vagrant::Errors::UploadInvalidCompressionType,
            type: options[:compression_type],
            valid_types: VALID_COMPRESS_TYPES.join(", ")
        end
        options[:decompression_method] = "decompress_#{options[:compression_type]}".to_sym
        if !machine.guest.capability?(options[:decompression_method])
          raise Vagrant::Errors::UploadMissingExtractCapability,
            type: options[:compression_type]
        end
      end

      # Compress path using zip into temporary file
      #
      # @param [String] path Path to compress
      # @return [String] path to compressed file
      def compress_source_zip(path)
        require "zip"
        zipfile = Tempfile.create(["vagrant", ".zip"])
        zipfile.close
        if File.file?(path)
          source_items = [path]
        else
          source_items = Dir.glob(File.join(path, "**", "**", "*"))
        end
        c_dir = nil

View on GitHub (pinned to 35f3160f4a)

Solutions

Retry without compression: drop `-c/--compress` and `-C`
Switch to the type the guest can extract: Windows-flavored guests support `zip`, common Linux guests support `tgz`
Use a more standard box whose guest OS is detected correctly (check via `vagrant ssh` and `cat /etc/os-release`) so capabilities resolve

Example fix

# before
vagrant upload -c -C tgz ./site/ /var/www   # guest cannot decompress_tgz

# after
vagrant upload ./site/ /var/www             # uncompressed upload succeeds

Defensive patterns

Strategy: fallback

Validate before calling

cap = "decompress_#{type}".to_sym
abort "guest lacks #{cap}; retry without --compress" unless machine.guest.capability?(cap)

Try / catch

begin
  command.execute
rescue Vagrant::Errors::UploadMissingExtractCapability
  system('vagrant', 'upload', src, dst)  # fallback: uncompressed upload
end

Prevention

Skip --compress for minimal or appliance-like guests
Match compression type to the guest platform (zip on Windows guests, tgz on Linux)
Smoke-test uploads against new boxes before adding compression to pipelines

When it happens

Trigger: `--compress`/`-C tgz` against a minimal guest whose detected guest plugin lacks `decompress_tgz`; forcing `-C zip` on a Linux guest without the zip decompression capability; guest OS detection falling through to a generic fallback host with few capabilities.

Common situations: Tiny containers or custom base boxes where guest detection fails; uploading .zip archives to Linux guests because the file happens to be a zip; old Vagrant versions missing newer guest implementations.

Related errors

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