puppetlabs/puppet · error · Puppet::Error

error while rendering epp

Error message

error while rendering epp

What it means

Raised at the end of `puppet epp render` when rendering one or more files produced a `Puppet::ParseError`: the per-file rescue prints the error with `Puppet.err`, sets `status = false`, and after all files the final `raise ... unless status` fires. Renderable files have already been written to the buffer, but the face API is all-or-nothing so the output string is discarded and the command exits non-zero. The real diagnostic is the Puppet.err line printed above the raise.

Source

Thrown at lib/puppet/face/epp.rb:359

        if options[:e]
          buffer.print render_inline(options[:e], compiler, options)
        elsif args.empty?
          if !STDIN.tty?
            buffer.print render_inline(STDIN.read, compiler, options)
          else
            raise Puppet::Error, _("No input to process given on command line or stdin")
          end
        else
          show_filename = args.count > 1
          file_nbr = 0
          args.each do |file|
            buffer.print render_file(file, compiler, options, show_filename, file_nbr += 1)
          rescue Puppet::ParseError => detail
            Puppet.err(detail.message)
            status = false
          end
        end
        raise Puppet::Error, _("error while rendering epp") unless status

        buffer.string
      end
    end
  end

  def dump_parse(source, filename, options, show_filename = true)
    output = ''.dup
    evaluating_parser = Puppet::Pops::Parser::EvaluatingParser::EvaluatingEppParser.new
    begin
      if options[:validate]
        parse_result = evaluating_parser.parse_string(source, filename)
      else
        # side step the assert_and_report step
        parse_result = evaluating_parser.parser.parse_string(source)
      end
      if show_filename && options[:header]
        output << "--- #{filename}\n"

View on GitHub (pinned to e227c27540)

Solutions

1. Read the Puppet.err line above the raise — it carries the template name and the parse/evaluation error
2. Supply required parameters: `puppet epp render t.epp --values @values.json`
3. Check the EPP parameter block (`<%# parameters: ... -%>`) matches the values you pass
4. Validate first (`puppet epp validate t.epp`) and inspect the AST with `puppet epp dump t.epp`

Example fix

# before
puppet epp render web/vhost.epp                      # required params missing
# after
cat > values.json <<'JSON'
{ "port": 8080, "name": "app" }
JSON
puppet epp render web/vhost.epp --values @values.json

require 'puppet/pops/parser/evaluating_parser'
parser = Puppet::Pops::Parser::EvaluatingParser::EvaluatingEppParser.new
begin
  parser.parse_string(File.read(template), template)
rescue Puppet::ParseError => e
  abort "#{template}: #{e.message}"
end

begin
  out = Puppet::Face[:epp, :current].render(files, values: params)
rescue Puppet::Error => e
  # message is 'error while rendering epp'; the Puppet.err lines above name the file and cause
  files.each { |f| Puppet::Face[:epp, :current].validate(f) rescue nil }
  raise
end

When it happens

Trigger: A template that parses but raises a ParseError during evaluation — references that fail parsing rules, EPP parameter-tag problems — or has outright syntax errors; with multiple files any single failure latches status even though the rest rendered.

Common situations: Rendering templates whose declared parameters are not supplied via --values; ERB-to-EPP migration leftovers; strict variable/undefined-variable behavior surfacing during render.

Related errors

• --- #{epp_template_name}
• One or more file(s) specified did not exist: %{missing_files
• Errors while validating epp
• --- #{filename}
• Could not load --values_file %{error}

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