puppetlabs/puppet · error · RuntimeError

Could not extract contents of module archive: %{message}

Error message

Could not extract contents of module archive: %{message}

What it means

Puppet raises this RuntimeError when a module tarball downloaded from the Forge cannot be extracted. The Unpacker shells out to the system tar; when tar exits non-zero, Puppet::ExecutionFailure is caught and re-raised with tar's message embedded. Root causes are almost always a corrupted or truncated archive (often the follow-on of a bad download), or a local tar that cannot handle the archive's compression format.

Source

Thrown at lib/puppet/forge.rb:228

      unless response.code == 200
        raise Puppet::Forge::Errors::ResponseError.new(:uri => response.url, :response => response)
      end
    end

    def validate_checksum(file, checksum, digest_class)
      if Puppet.runtime[:facter].value(:fips_enabled) && digest_class == Digest::MD5
        raise _("Module install using MD5 is prohibited in FIPS mode.")
      end

      if digest_class.file(file.path).hexdigest != checksum
        raise RuntimeError, _("Downloaded release for %{name} did not match expected checksum %{checksum}") % { name: name, checksum: checksum }
      end
    end

    def unpack(file, destination)
      Puppet::ModuleTool::Applications::Unpacker.unpack(file.path, destination)
    rescue Puppet::ExecutionFailure => e
      raise RuntimeError, _("Could not extract contents of module archive: %{message}") % { message: e.message }
    end

    def deprecated?
      @data['module'] && !@data['module']['deprecated_at'].nil?
    end
  end

  private

  def process(list)
    l = list.map do |release|
      metadata = release['metadata']
      begin
        ModuleRelease.new(self, release)
      rescue ArgumentError => e
        Puppet.warning _("Cannot consider release %{name}-%{version}: %{error}") % { name: metadata['name'], version: metadata['version'], error: e }
        false
      end

View on GitHub (pinned to e227c27540)

Solutions

1. Read the embedded tar message. It separates 'corrupt archive' from 'unsupported format'.
2. Download the tarball manually and run tar tzf <file>. If that fails, the archive itself is bad: re-download or fix the proxy/mirror, then retry the install.
3. If the format is the problem, install full extraction tooling on the node (apk add tar gzip xz, or apt-get install tar xz-utils) and retry.
4. Free disk space on the extraction target filesystem and retry.
5. Upgrade Puppet on the agent; newer versions support more compression formats and pass safer flags to tar.

Example fix

# before: busybox tar cannot extract the forge tarball
FROM alpine:3.19
RUN apk add --no-cache ruby
# puppet module install ... -> Could not extract contents of module archive: tar: unrecognized option

# after: full GNU tar plus compression libraries before any module install
FROM alpine:3.19
RUN apk add --no-cache ruby tar gzip xz

# Verify the extractors the Unpacker shells out to before installing modules
%w[tar gzip].each do |bin|
  abort "missing extractor: #{bin}" unless Puppet::Util::Which.which(bin)
end

begin
  Puppet::ModuleTool::Applications::Installer.run(mod, modulepath: mp)
rescue RuntimeError => e
  raise unless e.message =~ /Could not extract contents of module archive/
  raise unless e.message.include?('tar')  # tooling problem: do not blind-retry
  system('apk add tar xz') || system('apt-get install -y tar xz-utils')
  retry_once ? (retry_once = false; retry) : raise
end

When it happens

Trigger: A 'puppet module install' where the downloaded .tar.gz fails extraction: tar reports 'This does not look like a tar archive' or gzip reports 'unexpected end of file'. Also triggered when the module was packed with a compression the host tar lacks (for example xz or zstd on busybox or old GNU tar), or when extraction runs out of disk.

Common situations: Alpine or slim Docker images that ship busybox tar without xz/zstd support; truncated downloads behind flaky proxies; full filesystems during extraction; modules built by newer tooling being installed by agents with older tar binaries.

Related errors

• Downloaded release for %{name} did not match expected checks
• Could not extract contents of module archive: %{message}
• Could not %{action} '%{module_name}', did you mean '%{sugges
• Malformed dependency: %{name}. Exception was: %{detail}
• Could not %{action} '%{module_name}'; no releases are availa

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/a71a19da179b5856. Report an issue: GitHub.