puppetlabs/puppet · error · Puppet::Error

Could not autoload %{name}: %{detail}

Error message

Could not autoload %{name}: %{detail}

What it means

Puppet::Util::Autoload#load_file marks a name loaded and Kernel.load's the corresponding .rb file (an autoloaded provider, type, or face). SystemExit and NoMemoryError are re-raised untouched, but every other Exception is wrapped: Puppet.log_exception records it and a Puppet::Error 'Could not autoload %{name}: %{detail}' is raised with the original backtrace attached. The real cause is always in %{detail} — typically a SyntaxError, NameError, LoadError from a missing require, or an exception at class-evaluation time in the loaded file.

Source

Thrown at lib/puppet/util/autoload.rb:90

      end
    end

    # Load a single plugin by name.  We use 'load' here so we can reload a
    # given plugin.
    def load_file(name, env)
      file = get_file(name.to_s, env)
      return false unless file

      begin
        mark_loaded(name, file)
        Kernel.load file
        true
      rescue SystemExit, NoMemoryError
        raise
      rescue Exception => detail
        message = _("Could not autoload %{name}: %{detail}") % { name: name, detail: detail }
        Puppet.log_exception(detail, message)
        raise Puppet::Error, message, detail.backtrace
      end
    end

    def loadall(path, env)
      # Load every instance of everything we can find.
      files_to_load(path, env).each do |file|
        name = file.chomp(".rb")
        load_file(name, env) unless loaded?(name)
      end
    end

    def reload_changed(env)
      loaded.keys.each do |file|
        if changed?(file, env)
          load_file(file, env)
        end
      end
    end

View on GitHub (pinned to e227c27540)

Solutions

1. Read the %{detail} portion of the message — it names the real exception and file:line
2. Syntax-check the file: ruby -c /path/to/the/mentioned/file.rb
3. Install missing runtime dependencies (gems) on the node, or fix the broken require
4. Pin/upgrade the module to a release matching your Puppet version (puppet module upgrade)

Example fix

# before (module file has a syntax error, e.g. lib/puppet/provider/foo/bar.rb)
class Puppet::Provider::Foo::Bar < Puppet::Provider
  def self.instances   # missing 'end' below
end

# after
class Puppet::Provider::Foo::Bar < Puppet::Provider
  def self.instances
    []
  end
end

# Syntax-check module files before deploy
require 'ruby_vm/instruction_sequence'
Dir['modules/*/lib/puppet/**/*.rb'].each do |f|
  RubyVM::InstructionSequence.compile(File.read(f))
rescue SyntaxError => e
  abort "#{f}: #{e.message}"
end

begin
  Puppet::Util::Autoload.new(self, 'puppet/provider/foo').load(:myprovider, env)
rescue Puppet::Error => e
  # 'Could not autoload ...' — inspect e.cause/backtrace for the real exception
  Puppet.err "module load failed: #{e.message}"
end

When it happens

Trigger: A provider/type file under a module's lib/ or Puppet's own libdir containing a syntax error; the file requiring a gem that is not installed; the loaded file referencing a Puppet API constant removed in the running version; a custom provider failing at load time (e.g. Facter call at class scope). Trigger fires as soon as Puppet resolves the resource's provider during compilation.

Common situations: Module versions incompatible with the installed Puppet (major-version API removals); missing gem dependencies on the agent; partially-deployed or hand-edited module files; case errors in file names vs. autoloaded constants.

Related errors

• The code loaded from %{source_ref} does not define the type
• The code loaded from %{source_ref} produced type with the wr
• PathPatterns cannot be created with a zero byte.
• Request to Puppet Forge failed. Detail: %{detail}.
• Unable to verify the SSL certificate at %{uri}

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