puppetlabs/puppet · error · Puppet::Error

Unable to load class #{class_name}

Error message

Unable to load class #{class_name}

What it means

When an Object type has an entry in the implementation registry mapping it to a Ruby class, PObjectType#implementation_class resolves that name through ClassLoader. If the class cannot be provided (nil), Puppet::Error reports the unmappable class name — the mapping exists but the Ruby side does not resolve.

Source

Thrown at lib/puppet/pops/types/p_object_type.rb:563

        end
      end
    end
  end

  # @api private
  def implementation_class(create = true)
    if @implementation_class.nil? && create
      ir = Loaders.implementation_registry
      class_name = ir.nil? ? nil : ir.module_name_for_type(self)
      if class_name.nil?
        # Use generator to create a default implementation
        @implementation_class = RubyGenerator.new.create_class(self)
        @implementation_class.class_eval(&@implementation_override) if instance_variable_defined?(:@implementation_override)
      else
        # Can the mapping be loaded?
        @implementation_class = ClassLoader.provide(class_name)

        raise Puppet::Error, "Unable to load class #{class_name}" if @implementation_class.nil?
        unless @implementation_class < PuppetObject || @implementation_class.respond_to?(:ecore)
          raise Puppet::Error, "Unable to create an instance of #{name}. #{class_name} does not include module #{PuppetObject.name}"
        end
      end
    end
    @implementation_class
  end

  # @api private
  def implementation_class=(cls)
    raise ArgumentError, "attempt to redefine implementation class for #{label}" unless @implementation_class.nil?

    @implementation_class = cls
  end

  # The block passed to this method will be passed in a call to `#class_eval` on the dynamically generated
  # class for this data type. It's indended use is to complement or redefine the generated methods and
  # attribute readers.

View on GitHub (pinned to e227c27540)

Solutions

1. Verify the mapping: check the implementation registry / module metadata for the type and confirm the class name and namespace are exactly right.
2. Load it manually in a Ruby shell (puppet ruby -e or bundle exec ruby) to expose the real load error: require the file, then Object.const_defined?('PuppetX::Mod::Klass').
3. Ensure the module providing the Ruby implementation is present and enabled in the active environment so its lib dir is on the load path.
4. If no Ruby implementation is intended, remove the mapping so Puppet generates a default implementation class.

Example fix

# before — mapping points at a class that no longer exists
# (implementation registry / module metadata maps MyType -> PuppetX::Mymod::OldName)

# after — map to the existing class (lib/puppet_x/mymod/new_name.rb)
# PuppetX::Mymod::NewName, or drop the mapping for a generated default class

# Ruby — preflight the mapping before instantiating
klass = Puppet::Pops::Types::ClassLoader.provide(mapped_class_name)
fail("implementation #{mapped_class_name} for #{type.name} is not loadable") if klass.nil?

def implementation_loadable?(class_name)
  !Puppet::Pops::Types::ClassLoader.provide(class_name).nil?
end

begin
  obj_type.implementation_class # or obj_type.new(...)
rescue Puppet::Error => e
  raise LoadError, "#{e.message} — check module presence, load path, and type-to-class mapping"
end

When it happens

Trigger: Creating instances of an Object type (MyType.new(...) or New()(MyType)) whose registered implementation class name does not exist or fails to load: not on the Ruby load path, defined in a module missing from the active environment, wrong namespace, or a stale mapping after a rename.

Common situations: Module with type-to-class metadata referencing a class renamed or moved in a newer version; environment isolation hiding the module's lib directory; a gem dependency not installed so the implementing class is absent; case mismatch in the mapped name on Linux.

Related errors

• Loading of #{name} using relative path: '#{loaded_path}' did
• Unable to create an instance of #{name}. #{class_name} does
• attempt to redefine implementation class for #{label}
• Illegal format '#{actual}' specified for value of Object typ
• The code loaded from %{source_ref} must contain only the pla

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