puppetlabs/puppet · critical · LoadError

Puppet #{Puppet.version} requires Ruby #{Puppet::OLDEST_RECO

Error message

Puppet #{Puppet.version} requires Ruby #{Puppet::OLDEST_RECOMMENDED_RUBY_VERSION} or greater, found Ruby #{RUBY_VERSION.dup}.

What it means

At the top of lib/puppet.rb, RUBY_VERSION is compared against Puppet::OLDEST_RECOMMENDED_RUBY_VERSION ('3.1.0' in this tree) and a LoadError is raised immediately on older interpreters. Nothing else in the gem loads past this check — puppet refuses to run on an unsupported Ruby at require time.

Source

Thrown at lib/puppet.rb:8

# frozen_string_literal: true

require_relative 'puppet/version'
require_relative 'puppet/concurrent/synchronized'

Puppet::OLDEST_RECOMMENDED_RUBY_VERSION = '3.1.0'
if Gem::Version.new(RUBY_VERSION.dup) < Gem::Version.new(Puppet::OLDEST_RECOMMENDED_RUBY_VERSION)
  raise LoadError, "Puppet #{Puppet.version} requires Ruby #{Puppet::OLDEST_RECOMMENDED_RUBY_VERSION} or greater, found Ruby #{RUBY_VERSION.dup}."
end

$LOAD_PATH.extend(Puppet::Concurrent::Synchronized)

# see the bottom of the file for further inclusions
# Also see the new Vendor support - towards the end
#
require_relative 'puppet/error'
require_relative 'puppet/util'
require_relative 'puppet/util/autoload'
require_relative 'puppet/settings'
require_relative 'puppet/util/feature'
require_relative 'puppet/util/suidmanager'
require_relative 'puppet/util/run_mode'
require_relative 'puppet/gettext/config'
require_relative 'puppet/defaults'

# Defines the `Puppet` module. There are different entry points into Puppet

View on GitHub (pinned to e227c27540)

Solutions

1. Run through the puppet-agent all-in-one package, which bundles a supported Ruby (invoke via /opt/puppetlabs/puppet/bin/ruby)
2. Install Ruby >= 3.1 (rbenv/rvm/distro package) and reinstall the puppet gem under that interpreter
3. Or pin a puppet major version matching your interpreter (e.g. Puppet 7 supports Ruby >= 2.7)
4. Confirm which interpreter is loading puppet: ruby -v, which ruby, gem env

Example fix

# before (system ruby 2.7)
gem install puppet  # LoadError at require

# after
rbenv install 3.2.2 && rbenv local 3.2.2
gem install puppet

required = '3.1.0'
if Gem::Version.new(RUBY_VERSION) < Gem::Version.new(required)
  abort "puppet needs Ruby >= #{required}; running #{RUBY_VERSION} (#{RUBY_PATH})"
end
require 'puppet'

begin
  require 'puppet'
rescue LoadError => e
  abort "#{e.message} — switch to the puppet-agent ruby or upgrade Ruby"
end

When it happens

Trigger: require 'puppet' (or any puppet/puppetserver entry point loading it) under Ruby < 3.1.0: system Ruby 2.6/2.7 on CentOS 7 or Ubuntu 20.04; an rbenv/rvm shim resolving to an old default; the puppet gem installed onto a distro Ruby.

Common situations: Installing a modern puppet gem on an old distro Ruby; CI images pinned to legacy Rubies; switching from the all-in-one puppet-agent package to the gem and forgetting the bundled interpreter requirement.

Related errors

• Invalid entry at %{error_location}: '%{file_text}'
• %{mount} is already mounted at %{name} at %{error_location}
• Fileset paths must be fully qualified: %{path}
• Fileset paths must exist
• Invalid option '%{option}'

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