What causes "--- #{filename}" in puppetlabs/puppet?

Fix the error on the line printed after each header — it names the file and line

--- #{filename}

Error message

--- #{filename}

What it means

Printed during `puppet parser validate` with multiple manifests: for each file raising Puppet::ParseError, with show_filename on, a '--- <file>' header precedes the parse error message and that file's output becomes ''. Validation continues with the remaining files, so one header plus message pair appears per broken manifest.

Source

Thrown at lib/puppet/face/parser.rb:204

      if show_filename
        output << "--- #{filename}"
      end
      fmt = options[:format]
      if fmt.nil? || fmt == 'old'
        output << Puppet::Pops::Model::ModelTreeDumper.new.dump(parse_result) << "\n"
      else
        require_relative '../../puppet/pops/pn'
        pn = Puppet::Pops::Model::PNTransformer.transform(parse_result)
        case fmt
        when 'json'
          options[:pretty] ? JSON.pretty_unparse(pn.to_data) : JSON.dump(pn.to_data)
        else
          pn.format(options[:pretty] ? Puppet::Pops::PN::Indent.new('  ') : nil, output)
        end
      end
    rescue Puppet::ParseError => detail
      if show_filename
        Puppet.err("--- #{filename}")
      end
      Puppet.err(detail.message)
      ""
    end
  end

  # @api private
  def validate_manifest(manifest = nil)
    env = Puppet.lookup(:current_environment)
    loaders = Puppet::Pops::Loaders.new(env)

    Puppet.override({ :loaders => loaders }, _('For puppet parser validate')) do
      validation_environment = manifest ? env.override_with(:manifest => manifest) : env
      validation_environment.check_for_reparse
      validation_environment.known_resource_types.clear
    rescue Puppet::ParseError => parse_error
      return parse_error
    end

View on GitHub (pinned to e227c27540)

Solutions

Fix the error on the line printed after each header — it names the file and line
Iterate on a single file with `puppet parser validate <file>`
Wire `puppet parser validate` into pre-commit hooks and CI to catch manifests early

Example fix

# before (site.pp)
node default { notify { 'hi: } }

# after
node default { notify { 'hi': } }

Defensive patterns

Strategy: try-catch

Validate before calling

require 'puppet/pops/parser/evaluating_parser'

failed = []
Dir['**/*.pp'].each do |f|
  begin
    Puppet::Pops::Parser::EvaluatingParser.new.parse_file(f)
  rescue Puppet::ParseError => e
    warn "--- #{f}"
    warn e.message
    failed << f
  end
end
exit 1 unless failed.empty?

Try / catch

begin
  parser.parse_file(manifest)
rescue Puppet::ParseError => e
  Puppet.err "--- #{manifest}"
  Puppet.err e.message
  ""                          # mirror the face: report and continue with other files
end

Prevention

Add `puppet parser validate .` as a CI gate for modules and site manifests
Use pre-commit hooks that validate the staged .pp files

When it happens

Trigger: `puppet parser validate manifests/ 'site/*.pp'` where any file has invalid Puppet DSL: unmatched braces, bad expressions, reserved words — the EvaluatingParser#parse_file call raises Puppet::ParseError and the rescue prints the header.

Common situations: CI syntax gates over site/ and modules/; manifests authored for a newer or older grammar; generated manifests with template substitution bugs.

Related errors

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