{"record":{"id":"cd52ead0332a52f1","repo":"puppetlabs/puppet","slug":"no-suitable-tar-implementation-found","errorCode":null,"errorMessage":"No suitable tar implementation found","messagePattern":"No suitable tar implementation found","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"lib/puppet/module_tool/tar.rb","lineNumber":17,"sourceCode":"# frozen_string_literal: true\n\nrequire_relative '../../puppet/module_tool'\nrequire_relative '../../puppet/util'\n\nmodule Puppet::ModuleTool::Tar\n  require_relative 'tar/gnu'\n  require_relative 'tar/mini'\n\n  def self.instance\n    if Puppet.features.minitar? && Puppet.features.zlib?\n      Mini.new\n    elsif Puppet::Util.which('tar') && !Puppet::Util::Platform.windows?\n      Gnu.new\n    else\n      # TRANSLATORS \"tar\" is a program name and should not be translated\n      raise RuntimeError, _('No suitable tar implementation found')\n    end\n  end\nend\n","sourceCodeStart":1,"sourceCodeEnd":21,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/module_tool/tar.rb#L1-L21","documentation":"Puppet::ModuleTool::Tar.instance selects the backend used to unpack module packages: the pure-Ruby Mini backend when the minitar and zlib features both load, otherwise GNU tar when a 'tar' binary is on PATH and the platform is not Windows. When neither condition holds, this RuntimeError fires before any package can be extracted — the host simply has no way to unpack tarballs.","triggerScenarios":"Any 'puppet module install'/'upgrade' on a POSIX host where the minitar/zlib ruby libraries are missing and 'tar' is not on PATH (distroless or slim containers, stripped service environments), or on Windows without minitar, since the GNU fallback is disabled there.","commonSituations":"Minimal Docker images without tar; 'gem install puppet' with skipped dependencies; systemd/cron units with a stripped PATH so which('tar') fails; Windows hosts without the puppet-agent package.","solutions":["Install the missing Ruby libraries: gem install minitar (zlib ships with ruby) — this is the normal dependency set of the puppet gem.","On POSIX, ensure tar exists and is on PATH for the puppet process: apk add tar / apt-get install -y tar, then verify with 'which tar' under that same environment.","Prefer the official puppet-agent package, which bundles a complete toolchain on all platforms.","For services, set an explicit PATH (e.g. /usr/bin:/bin) in the unit or cron entry so which('tar') succeeds."],"exampleFix":"# before\n$ docker run myslim puppet module install puppetlabs-stdlib\nError: No suitable tar implementation found\n\n# after\n$ docker run myslim sh -c 'apk add --no-cache tar && puppet module install puppetlabs-stdlib'","handlingStrategy":"validation","validationCode":"def tar_backend?\n  (Puppet.features.minitar? && Puppet.features.zlib?) ||\n    (!Puppet::Util::Platform.windows? && !Puppet::Util.which('tar').nil?)\nend\nraise 'no tar backend available — install minitar or system tar' unless tar_backend?","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::ModuleTool::Tar.instance\nrescue RuntimeError => e\n  raise unless e.message.include?('tar implementation')\n  abort 'puppet cannot unpack modules here: gem install minitar, or install tar'\nend","preventionTips":["Add a preflight to container builds: ruby -r puppet/module_tool/tar -e 'Puppet::ModuleTool::Tar.instance'.","Base automation images on official puppet-agent images.","Never strip PATH in service units or cron entries that run puppet module commands.","Keep the puppet gem's full dependency set; never install with --ignore-dependencies."],"tags":["puppet","ruby","module-tool","tar","environment","docker","windows"],"backgroundTag":"missing-system-dependency","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}