puppetlabs/puppet · error · Puppet::Error

Unable to load application class '%{class_name}' from file '

Error message

Unable to load application class '%{class_name}' from file 'puppet/application/%{application_name}.rb'

What it means

Puppet::Application.find resolves 'puppet <name>' by loading puppet/application/<name>.rb and looking up the constant Puppet::Application::<name.capitalize> (plus a 2.7.x compatibility fallback). If the constant still isn't defined after that, Puppet::Error is raised: the file was found on the load path but did not define the expected class.

Source

Thrown at lib/puppet/application.rb:254

      class_name = Puppet::Util::ConstantInflector.file2constant(application_name.to_s)

      clazz = try_load_class(class_name)

      ################################################################
      #### Begin 2.7.x backward compatibility hack;
      ####  eventually we need to issue a deprecation warning here,
      ####  and then get rid of this stanza in a subsequent release.
      ################################################################
      if clazz.nil?
        class_name = application_name.capitalize
        clazz = try_load_class(class_name)
      end
      ################################################################
      #### End 2.7.x backward compatibility hack
      ################################################################

      if clazz.nil?
        raise Puppet::Error, _("Unable to load application class '%{class_name}' from file 'puppet/application/%{application_name}.rb'") % { class_name: class_name, application_name: application_name }
      end

      clazz
    end

    # Given the fully qualified name of a class, attempt to get the class instance.
    # @param [String] class_name the fully qualified name of the class to try to load
    # @return [Class] the Class instance, or nil? if it could not be loaded.
    def try_load_class(class_name)
      const_defined?(class_name) ? const_get(class_name) : nil
    end
    private :try_load_class

    # Return an instance of the specified application.
    #
    # @param [Symbol] name the lowercase name of the application
    # @return [Puppet::Application] an instance of the specified name
    # @raise [Puppet::Error] if the application class was not found.

View on GitHub (pinned to e227c27540)

Solutions

1. Name the class exactly as String#capitalize will produce from the file name: mytool.rb defines Puppet::Application::Mytool; prefer single-token application names to sidestep capitalize's behavior on underscores
2. Verify it loads standalone: ruby -e "require 'puppet/application/mytool'; p Puppet::Application::Mytool"
3. Ensure the file is on $LOAD_PATH (module lib dir actually deployed to the node) and has no silent require failures
4. Check for typos between the subcommand word and the file name first — find only loads the matching file

Example fix

# lib/puppet/application/my_tool.rb
# before
module Puppet; module Application
class MyApp < Puppet::Application  # 'my_tool'.capitalize == 'My_tool', no match
end; end; end

# after  (or rename the file/command to 'myapp')
module Puppet; module Application
class My_tool < Puppet::Application  # matches Application.find lookup
end; end; end

require 'puppet/application/mytool'
raise LoadError, 'plugin broken' unless Puppet::Application.const_defined?(:Mytool)

begin
  Puppet::Application.find('mytool')
rescue Puppet::Error => e
  # class/file naming mismatch — check e.message for expected class name
  raise "mytool plugin failed to load: #{e.message}"
end

When it happens

Trigger: Shipping lib/puppet/application/my_tool.rb that defines Puppet::Application::MyTool — 'my_tool'.capitalize is 'My_tool', so underscored compound names never match unless the constant is cased exactly as capitalize produces; the file failing to require cleanly; the class defined under a different namespace.

Common situations: Face/application plugins from modules or gems with naming mismatches; plugin upgrades that renamed the class; authors assuming Rails-style camelize instead of String#capitalize.

Related errors

• Invalid environment mode '%{mode_name}'
• Function Load Error for function '%{function_name}': %{messa
• The loaded Fiddle version is not supported.
• PathPatterns cannot be created with a zero byte.
• Request to Puppet Forge failed. Detail: %{detail}.

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