puppetlabs/puppet · error · Puppet::ParseError

%{param} is a metaparameter; please choose another parameter

Error message

%{param} is a metaparameter; please choose another parameter name in the %{name} definition

What it means

Puppet::Resource::Type#warn_if_metaparam fires when a class or defined type declares a parameter whose name is a metaparameter (require, before, notify, subscribe, audit, loglevel, alias, tag, schedule, stage...). With a default value it only emits a warning (the value would inherit into all contained resources); without a default value it raises Puppet::ParseError, because the metaparam semantics would silently shadow user intent.

Source

Thrown at lib/puppet/resource/type.rb:420

      @name = name
      @namespace = ""
    else
      @name = name.to_s.downcase

      # Note we're doing something somewhat weird here -- we're setting
      # the class's namespace to its fully qualified name.  This means
      # anything inside that class starts looking in that namespace first.
      @namespace, _ = @type == :hostclass ? [@name, ''] : namesplit(@name)
    end
  end

  def warn_if_metaparam(param, default)
    return unless Puppet::Type.metaparamclass(param)

    if default
      warnonce _("%{param} is a metaparam; this value will inherit to all contained resources in the %{name} definition") % { param: param, name: name }
    else
      raise Puppet::ParseError, _("%{param} is a metaparameter; please choose another parameter name in the %{name} definition") % { param: param, name: name }
    end
  end

  def parameter_struct
    @parameter_struct ||= create_params_struct
  end

  def create_params_struct
    arg_types = argument_types
    type_factory = Puppet::Pops::Types::TypeFactory
    members = { type_factory.optional(type_factory.string(NAME)) => type_factory.any }

    Puppet::Type.eachmetaparam do |name|
      # TODO: Once meta parameters are typed, this should change to reflect that type
      members[name.to_s] = type_factory.any
    end

    arguments.each_pair do |name, default|

View on GitHub (pinned to e227c27540)

Solutions

1. Rename the parameter to a non-metaparam name: $require -> $requires or $pkg_to_require, $notify -> $notify_service, $alias -> $aka.
2. If the parameter must keep its name for API compatibility, give it a default value (only a warning is emitted) and internally use the parameter explicitly rather than relying on inheritance.
3. Audit parameter lists of your modules against Puppet::Type metaparam names and fix all collisions at once.

Example fix

# before
define monitor::service($service_name, $notify) {
  service { $service_name:
    ensure => running,
  }
}

# after
define monitor::service($service_name, $notify_service = undef) {
  service { $service_name:
    ensure  => running,
    notify  => $notify_service,
  }
}

# reject parameter names that collide with metaparameters before defining types
METAPARAMS = Puppet::Type.alltypes.flat_map { |t| t.metaparams }.uniq.map(&:to_s)
params.each do |p|
  raise ArgumentError, "parameter #{p} collides with a metaparameter" if METAPARAMS.include?(p.to_s)
end

safe_param_name = ->(name) { Puppet::Type.metaparamclass(name.to_sym).nil? }

begin
  # load the definition / compile the manifest
rescue Puppet::ParseError => e
  raise unless e.message.include?('is a metaparameter')
  Puppet.err("rename the parameter named in: #{e.message}")
  raise
end

When it happens

Trigger: Writing `define monitor::check($service_name, $notify)` (no default) — raises; `define apache::vhost($port, $require = undef)` — warns because every contained resource inheriting $require changes behavior. The check runs when the definition's parameter list is processed (Puppet::Type.metaparamclass(param) is truthy).

Common situations: Older or third-party modules that predate the check using parameters like $require or $notify; API-natural names colliding with metaparams ($alias, $tag); Puppet upgrades that made this stricter failing previously-working modules.

Related errors

• Function Load Error for function '%{function_name}': %{messa
• 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

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