{"record":{"id":"4e2a44fc2bbf1664","repo":"puppetlabs/puppet","slug":"could-not-extract-contents-of-module-archive-me-4e2a44","errorCode":null,"errorMessage":"Could not extract contents of module archive: %{message}","messagePattern":"Could not extract contents of module archive: %(.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"lib/puppet/module_tool/applications/unpacker.rb","lineNumber":59,"sourceCode":"        module_dir\n      end\n\n      # @api private\n      # Error on symlinks and other junk\n      def sanity_check\n        symlinks = Dir.glob(\"#{tmpdir}/**/*\", File::FNM_DOTMATCH).map { |f| Pathname.new(f) }.select { |p| Puppet::FileSystem.symlink? p }\n        tmpdirpath = Pathname.new tmpdir\n\n        symlinks.each do |s|\n          Puppet.warning _(\"Symlinks in modules are unsupported. Please investigate symlink %{from}->%{to}.\") % { from: s.relative_path_from(tmpdirpath), to: Puppet::FileSystem.readlink(s) }\n        end\n      end\n\n      # @api private\n      def unpack\n        Puppet::ModuleTool::Tar.instance.unpack(@filename.to_s, tmpdir, [@module_path.stat.uid, @module_path.stat.gid].join(':'))\n      rescue Puppet::ExecutionFailure => e\n        raise RuntimeError, _(\"Could not extract contents of module archive: %{message}\") % { message: e.message }\n      end\n\n      # @api private\n      def root_dir\n        return @root_dir if @root_dir\n\n        # Grab the first directory containing a metadata.json file\n        metadata_file = Dir[\"#{tmpdir}/**/metadata.json\"].min_by(&:length)\n\n        if metadata_file\n          @root_dir = Pathname.new(metadata_file).dirname\n        else\n          raise _(\"No valid metadata.json found!\")\n        end\n      end\n\n      # @api private\n      def module_name","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/module_tool/applications/unpacker.rb#L41-L77","documentation":"Unpacker#unpack extracts a downloaded module tarball by delegating to Puppet::ModuleTool::Tar.instance.unpack (a tar shell-out). If the underlying command fails, the Puppet::ExecutionFailure is re-raised as a plain RuntimeError with the command's error text appended. It almost always means the archive on disk is not a readable gzipped tar or the extraction environment is broken, not that Puppet logic failed.","triggerScenarios":"Calling Puppet::ModuleTool::Applications::Unpacker.run/archive extraction for a file that tar cannot process: a truncated download, an HTML proxy error page saved with a .tar.gz name, a non-gzip archive, or a system where the tar binary is missing/fails (disk full in the tmpdir).","commonSituations":"Interrupted `puppet module install` leaving a partial file in the Forge cache; corporate proxies or captive portals mangling downloads; Windows boxes without the module-tool tar shim; TMPDIR on a full filesystem; double-compressed or wrongly-packaged tarballs from a private Forge.","solutions":["Clear the Forge cache (delete the tarball under Puppet::Forge::Cache.base_path, ~/.puppet/cache or /opt/puppetlabs/puppet/cache) and retry the install","Verify the file is a valid gzipped tar before retrying: `tar -tzf <file>.tar.gz | head` (also `file <file>.tar.gz`)","Check disk space and writability of the temporary directory (df -h, echo $TMPDIR)","On Windows, ensure the bundled tar/gzip tooling that ships with Puppet is available on PATH, or install via a Puppet-provided package"],"exampleFix":"# before\n$ puppet module install puppetlabs-stdlib\n# Error: Could not extract contents of module archive: tar: This does not look like a tar archive\n\n# after\n$ rm -rf \"$(puppet config print module_working_dir)\"/*\n$ puppet module install puppetlabs-stdlib","handlingStrategy":"try-catch","validationCode":"def extractable?(tarball)\n  File.exist?(tarball) && File.size(tarball) > 0 &&\n    system('tar', '-tzf', tarball, out: File::NULL, err: File::NULL)\nend\n\nabort 'archive is not a readable gzipped tar' unless extractable?(archive)","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::ModuleTool::Applications::Unpacker.run(archive_file, destination)\nrescue RuntimeError => e\n  raise \"module archive unpack failed for #{archive_file}: #{e.message}\" unless e.message =~ /Could not extract/\n  Puppet::Forge::Cache.clean\n  retry once_after_redownload\nend","preventionTips":["Verify downloads before use: check Content-Length and run `tar -tzf` on cached tarballs","Clear the Forge cache after network interruptions instead of retrying on a partial file","Monitor disk space on the volume holding TMPDIR and the Puppet cache","On Windows, install Puppet from official packages so the tar helper is present"],"tags":["puppet","module-tool","tar","archive","extraction","download-corruption"],"backgroundTag":"archive-extraction-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}