puppetlabs/puppet · error · Puppet::Error

The parameter '$#{name}' is invalid: #{e.message}

Error message

The parameter '$#{name}' is invalid: #{e.message}

What it means

While extracting class documentation, ClassInformationService interprets each parameter's type expression with the POPS type parser (type_parser.interpret_any). If interpretation raises Puppet::ParseError, it is re-raised as Puppet::Error prefixed with the parameter name. The manifest's class parameter has a type expression the current Puppet version cannot resolve — e.g., an undefined type alias, a syntax error in the type, or an expression that is not a type at all (default-value expression leaking into the type slot).

Source

Thrown at lib/puppet/info_service/class_information_service.rb:94

    structure[:type] = typeexpr_to_string(p.name, p.type_expr)
    structure
  end

  def extract_default(structure, p)
    value_expr = p.value
    return structure if value_expr.nil?

    default_value = value_as_literal(value_expr)
    structure[:default_literal] = default_value unless default_value.nil?
    structure[:default_source] = extract_value_source(value_expr)
    structure
  end

  def typeexpr_to_string(name, type_expr)
    type_parser.interpret_any(type_expr, nil).to_s
  rescue Puppet::ParseError => e
    raise Puppet::Error, "The parameter '$#{name}' is invalid: #{e.message}", e.backtrace
  end

  def value_as_literal(value_expr)
    catch(:not_literal) do
      return literal_evaluator.literal(value_expr)
    end
    nil
  end

  # Extracts the source for the expression
  def extract_value_source(value_expr)
    value_expr.locator.extract_tree_text(value_expr)
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Open the manifest at the named parameter and fix the type expression (the embedded e.message carries file/line)
2. Verify the type alias resolves: run `puppet parser validate <manifest>` in the same environment/modulepath context
3. Ensure the module defining the alias is present under the environment's modulepath used by the extraction call
4. For version mismatches, run the doc/class-info task with the same Puppet version that compiles the code

Example fix

# before (manifest)
class ntp(
  Port::Unix $port = 123,   # Port::Unix alias not autoloadable in this env
) { }
# Error: The parameter '$port' is invalid: Undefined type 'Port::Unix'

# after
class ntp(
  Stdlib::Port $port = 123,  # stdlib present in modulepath
) { }

require 'puppet/pops'
parser = Puppet::Pops::Parser::EvaluatingParser.new
manifest_files.each do |f|
  parser.parse_file(f)  # raises Puppet::ParseError early with file/line
end

begin
  Puppet::InfoService::ClassInformationService.new.classes_per_environment(env_hash)
rescue Puppet::Error => e
  raise unless e.message =~ /\$\w+' is invalid/
  Puppet.warning "skipping #{e.message}"  # quarantine broken manifests, keep doc run alive
end

When it happens

Trigger: Running class-info extraction (puppet Strings adjacent tooling, puppetserver class endpoints) on a manifest like 'class web(NotAlias::Defined $port)' where NotAlias::Defined is never defined/autloaded, or 'class web(8080 $port)' where a literal sits in the type position, or a type expression using newer syntax on an older parser.

Common situations: Type aliases living in a module that is not in the modulepath when the doc extraction runs; manifests authored with future/newer Puppet syntax parsed by an older Puppet; typos in namespaced type aliases; parameter list syntax drift after language changes.

Related errors

• Parsing of 'type "%{assignment_string}"' failed with message
• Unable to connect to the server at %{uri}. Detail: %{detail}
• Expected a type alias assignment on the form 'AliasType = T'
• Could not parse JSON %{metadata_path}
• The code loaded from %{source_ref} does not define the type

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