{"record":{"id":"49b30eb02fc8317a","repo":"puppetlabs/puppet","slug":"could-not-extract-contents-of-module-archive-me-49b30e","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/local_tarball.rb","lineNumber":89,"sourceCode":"        @source.prepare(self)\n      end\n    end\n\n    private\n\n    # Obtain a suitable temporary path for unpacking tarballs\n    #\n    # @return [String] path to temporary unpacking location\n    # rubocop:disable Naming/MemoizedInstanceVariableName\n    def tmpdir\n      @dir ||= Dir.mktmpdir('local-tarball', Puppet::Forge::Cache.base_path)\n    end\n    # rubocop:enable Naming/MemoizedInstanceVariableName\n\n    def unpack(file, destination)\n      Puppet::ModuleTool::Applications::Unpacker.unpack(file, destination)\n    rescue Puppet::ExecutionFailure => e\n      raise RuntimeError, _(\"Could not extract contents of module archive: %{message}\") % { message: e.message }\n    end\n  end\nend\n","sourceCodeStart":71,"sourceCodeEnd":93,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/module_tool/local_tarball.rb#L71-L93","documentation":"LocalTarball#unpack (used when installing from a file: `puppet module install ./pkg.tar.gz`) delegates to Applications::Unpacker.unpack and rescues Puppet::ExecutionFailure, re-raising it as RuntimeError with this message. It fires when the tarball on disk cannot be extracted — malformed archive, wrong compression, or a failing tar environment — mirroring the Unpacker error but on the local-package path.","triggerScenarios":"Running `puppet module install ./my-module.tar.gz` where the file is not a valid gzipped tar produced by `puppet module build` — e.g. a plain directory tarballed without gzip, a zip renamed to .tar.gz, or a truncated file.","commonSituations":"Building tarballs with custom scripts that skip the metadata.json root layout; CI artifacts zipped then renamed; transferring modules through tools that mangle compression; empty 0-byte artifacts from a failed build job.","solutions":["Validate the archive first: `tar -tzf my-module.tar.gz` must list a single root directory containing metadata.json","Rebuild with the supported tool: `puppet module build` in the module directory, then install the fresh pkg/*.tar.gz","If the file came from CI, fix the packaging step (gzip the tar, keep the module-name/ root dir) instead of renaming other formats","Check disk space and TMPDIR, then retry after clearing the module working dir"],"exampleFix":"# before\n$ puppet module install ./my-module.tar.gz\n# Error: Could not extract contents of module archive: tar: Archive is compressed with unknown method\n\n# after\n$ cd my-module && puppet module build\n$ puppet module install ./pkg/my-module-0.1.0.tar.gz","handlingStrategy":"try-catch","validationCode":"def valid_module_tarball?(path)\n  return false unless File.exist?(path) && File.size(path) > 0\n  entries = `tar -tzf #{Shellwords.escape(path)}`.split(\"\\n\")\n  entries.any? { |e| e.end_with?('metadata.json') }\nrescue Errno::ENOENT\n  false\nend\n\nabort 'not a puppet module tarball (no metadata.json)' unless valid_module_tarball?(pkg)","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::ModuleTool::LocalTarball.new(pkg_path).unpack(pkg_path, dest)\nrescue RuntimeError => e\n  raise \"local tarball #{pkg_path} failed to extract: #{e.message} — rebuild with `puppet module build`\"\nend","preventionTips":["Build distributable archives exclusively with `puppet module build`","In CI, gate artifacts on containing a single root dir with metadata.json before publishing","Never rename zip/plain-tar artifacts to .tar.gz to satisfy installers"],"tags":["puppet","module-tool","local-tarball","tar","archive","install"],"backgroundTag":"archive-extraction-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}