puppetlabs/puppet · error · RuntimeError

No suitable tar implementation found

Error message

No suitable tar implementation found

What it means

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.

Source

Thrown at lib/puppet/module_tool/tar.rb:17

# frozen_string_literal: true

require_relative '../../puppet/module_tool'
require_relative '../../puppet/util'

module Puppet::ModuleTool::Tar
  require_relative 'tar/gnu'
  require_relative 'tar/mini'

  def self.instance
    if Puppet.features.minitar? && Puppet.features.zlib?
      Mini.new
    elsif Puppet::Util.which('tar') && !Puppet::Util::Platform.windows?
      Gnu.new
    else
      # TRANSLATORS "tar" is a program name and should not be translated
      raise RuntimeError, _('No suitable tar implementation found')
    end
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Install the missing Ruby libraries: gem install minitar (zlib ships with ruby) — this is the normal dependency set of the puppet gem.
2. 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.
3. Prefer the official puppet-agent package, which bundles a complete toolchain on all platforms.
4. For services, set an explicit PATH (e.g. /usr/bin:/bin) in the unit or cron entry so which('tar') succeeds.

Example fix

# before
$ docker run myslim puppet module install puppetlabs-stdlib
Error: No suitable tar implementation found

# after
$ docker run myslim sh -c 'apk add --no-cache tar && puppet module install puppetlabs-stdlib'

def tar_backend?
  (Puppet.features.minitar? && Puppet.features.zlib?) ||
    (!Puppet::Util::Platform.windows? && !Puppet::Util.which('tar').nil?)
end
raise 'no tar backend available — install minitar or system tar' unless tar_backend?

begin
  Puppet::ModuleTool::Tar.instance
rescue RuntimeError => e
  raise unless e.message.include?('tar implementation')
  abort 'puppet cannot unpack modules here: gem install minitar, or install tar'
end

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Attempt to install file with an invalid path into %{path} un
• Could not extract contents of module archive: %{message}
• Could not extract contents of module archive: %{message}
• '%{module_name}' (%{version}) requested; Invalid dependency
• Could not %{action} '%{module_name}' (%{version}); no versio

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