puppetlabs/puppet · error · ArgumentError

Function Load Error for function '%{function_name}': %{messa

Error message

Function Load Error for function '%{function_name}': %{message}

What it means

Puppet raises this ArgumentError while it creates a Ruby function from a Puppet::Functions.create_function block. Any StandardError raised during creation (a bad dispatch DSL call, an unparseable type string, a Ruby name error inside the block) is caught and re-raised with this wrapper text, and the original message is embedded. This is a definition-time error in the function's own Ruby file, not a call-time error.

Source

Thrown at lib/puppet/functions.rb:195

#
# @api public
module Puppet::Functions
  # @param func_name [String, Symbol] a simple or qualified function name
  # @param block [Proc] the block that defines the methods and dispatch of the
  #   Function to create
  # @return [Class<Function>] the newly created Function class
  #
  # @api public
  def self.create_function(func_name, function_base = Function, &block)
    # Ruby < 2.1.0 does not have method on Binding, can only do eval
    # and it will fail unless protected with an if defined? if the local
    # variable does not exist in the block's binder.
    #

    loader = block.binding.eval('loader_injected_arg if defined?(loader_injected_arg)')
    create_loaded_function(func_name, loader, function_base, &block)
  rescue StandardError => e
    raise ArgumentError, _("Function Load Error for function '%{function_name}': %{message}") % { function_name: func_name, message: e.message }
  end

  # Creates a function in, or in a local loader under the given loader.
  # This method should only be used when manually creating functions
  # for the sake of testing. Functions that are autoloaded should
  # always use the `create_function` method and the autoloader will supply
  # the correct loader.
  #
  # @param func_name [String, Symbol] a simple or qualified function name
  # @param loader [Puppet::Pops::Loaders::Loader] the loader loading the function
  # @param block [Proc] the block that defines the methods and dispatch of the
  #   Function to create
  # @return [Class<Function>] the newly created Function class
  #
  # @api public
  def self.create_loaded_function(func_name, loader, function_base = Function, &block)
    if function_base.ancestors.none? { |s| s == Puppet::Pops::Functions::Function }
      raise ArgumentError, _("Functions must be based on Puppet::Pops::Functions::Function. Got %{function_base}") % { function_base: function_base }

View on GitHub (pinned to e227c27540)

Solutions

1. Read the embedded %{message}. It names the real failure; fix that in the function file shown in the backtrace.
2. Reproduce with a minimal call (puppet apply -e 'notice(my_func())') or by loading the file in a ruby -Ilib session, so you see the full original backtrace.
3. If the message points at dispatcher or type DSL, check the function against stock functions shipped in your Puppet version; the DSL may be newer than your Puppet.
4. For third-party modules, pin a module release whose metadata.json supports your Puppet version, or upgrade Puppet.

Example fix

# before: nested parse error -> Function Load Error for function 'bad'
Puppet::Functions.create_function(:bad) do
  dispatch :bad do
    param 'Array[String', :xs   # unbalanced bracket
  end
  def bad(xs); xs; end
end

# after: valid type string, function loads cleanly
Puppet::Functions.create_function(:bad) do
  dispatch :bad do
    param 'Array[String]', :xs
  end
  def bad(xs); xs; end
end

# CI: force-load every function file so definition-time errors surface before deploy
Dir['site/*/lib/puppet/functions/**/*.rb'].sort.each { |f| load(f) }

begin
  Puppet::Pops::Loaders.find_loader(nil).load(:function, 'my_func')
rescue ArgumentError => e
  raise unless e.message =~ /Function Load Error/
  # Deterministic authoring bug: fail fast, surface the embedded %{message}
  raise "broken function definition: #{e.message}" 
end

When it happens

Trigger: The autoloader loads a file under lib/puppet/functions/ whose create_function block fails. Examples: param 'Array[String', :xs (unbalanced type string, surfaces as the nested 'Parsing of type string' error); a reference to a constant that does not exist; use of dispatcher DSL that the running Puppet version does not support.

Common situations: Custom functions written against a newer Puppet running on an older one; typos inside dispatch blocks; refactoring that renames a helper the block used; vendored function files with syntax errors that only load when the function is first called.

Related errors

• A required parameter cannot be added after an optional param
• block_param accepts max 2 arguments (type, name), got %{size
• Attempt to redefine block
• Argument to 'return_type' must be a String reference to a Pu
• Parameters cannot be added after a block parameter

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