{"record":{"id":"0726fb6197fd9c41","repo":"puppetlabs/puppet","slug":"unable-to-load-class-class-name","errorCode":null,"errorMessage":"Unable to load class #{class_name}","messagePattern":"Unable to load class #(.+?)","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/pops/types/p_object_type.rb","lineNumber":563,"sourceCode":"        end\n      end\n    end\n  end\n\n  # @api private\n  def implementation_class(create = true)\n    if @implementation_class.nil? && create\n      ir = Loaders.implementation_registry\n      class_name = ir.nil? ? nil : ir.module_name_for_type(self)\n      if class_name.nil?\n        # Use generator to create a default implementation\n        @implementation_class = RubyGenerator.new.create_class(self)\n        @implementation_class.class_eval(&@implementation_override) if instance_variable_defined?(:@implementation_override)\n      else\n        # Can the mapping be loaded?\n        @implementation_class = ClassLoader.provide(class_name)\n\n        raise Puppet::Error, \"Unable to load class #{class_name}\" if @implementation_class.nil?\n        unless @implementation_class < PuppetObject || @implementation_class.respond_to?(:ecore)\n          raise Puppet::Error, \"Unable to create an instance of #{name}. #{class_name} does not include module #{PuppetObject.name}\"\n        end\n      end\n    end\n    @implementation_class\n  end\n\n  # @api private\n  def implementation_class=(cls)\n    raise ArgumentError, \"attempt to redefine implementation class for #{label}\" unless @implementation_class.nil?\n\n    @implementation_class = cls\n  end\n\n  # The block passed to this method will be passed in a call to `#class_eval` on the dynamically generated\n  # class for this data type. It's indended use is to complement or redefine the generated methods and\n  # attribute readers.","sourceCodeStart":545,"sourceCodeEnd":581,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/pops/types/p_object_type.rb#L545-L581","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the mapping: check the implementation registry / module metadata for the type and confirm the class name and namespace are exactly right.","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').","Ensure the module providing the Ruby implementation is present and enabled in the active environment so its lib dir is on the load path.","If no Ruby implementation is intended, remove the mapping so Puppet generates a default implementation class."],"exampleFix":"# before — mapping points at a class that no longer exists\n# (implementation registry / module metadata maps MyType -> PuppetX::Mymod::OldName)\n\n# after — map to the existing class (lib/puppet_x/mymod/new_name.rb)\n# PuppetX::Mymod::NewName, or drop the mapping for a generated default class","handlingStrategy":"validation","validationCode":"# Ruby — preflight the mapping before instantiating\nklass = Puppet::Pops::Types::ClassLoader.provide(mapped_class_name)\nfail(\"implementation #{mapped_class_name} for #{type.name} is not loadable\") if klass.nil?","typeGuard":"def implementation_loadable?(class_name)\n  !Puppet::Pops::Types::ClassLoader.provide(class_name).nil?\nend","tryCatchPattern":"begin\n  obj_type.implementation_class # or obj_type.new(...)\nrescue Puppet::Error => e\n  raise LoadError, \"#{e.message} — check module presence, load path, and type-to-class mapping\"\nend","preventionTips":["Smoke-test each Object type's instantiation in CI with the full module path set up.","Keep type-to-class mappings in lockstep with class renames; grep both when refactoring."],"tags":["puppet","object-type","implementation-class","class-loading","module-structure"],"backgroundTag":"implementation-class-not-found","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}