What causes "Errors while validating epp" in puppetlabs/puppet?

Scroll up to the per-template error output — it names the file, line, and parse problem

puppetlabs/puppet · error · Puppet::Error

Errors while validating epp

Error message

Errors while validating epp

What it means

Raised by `puppet epp validate` when every named template was found but at least one failed to parse or validate: `validate_template` printed the per-file error and returned false, `status &&= tmp` latched the failure, and because `missing_files` is empty the final `raise ... unless status` fires. The actionable detail (file, line, parse error) is in the Puppet.err output printed just before this summary error, not in the message itself.

Source

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

      missing_files = []
      files.each do |file|
        break if !status && !options[:continue_on_error]

        template_file = effective_template(file, compiler.environment)
        if template_file
          tmp = validate_template(template_file)
          status &&= tmp
        else
          missing_files << file
        end
      end
      if !missing_files.empty?
        raise Puppet::Error, _("One or more file(s) specified did not exist:\n%{missing_files_list}") %
                             { missing_files_list: missing_files.map { |f| "   #{f}" }.join("\n") }
      else
        # Exit with 1 if there were errors
        raise Puppet::Error, _("Errors while validating epp") unless status
      end
    end
  end

  action(:dump) do
    summary _("Outputs a dump of the internal template parse tree for debugging")
    arguments "[--format <old|pn|json>] [--pretty] { -e <source> | [<templates> ...] } "
    returns _("A dump of the resulting AST model unless there are syntax or validation errors.")
    description <<-'EOT'
      The dump action parses and validates the EPP syntax and dumps the resulting AST model
      in a human readable (but not necessarily an easy to understand) format.

      The output format can be controlled using the --format <old|pn|json> where:
      * 'old' is the default, but now deprecated format which is not API.
      * 'pn' is the Puppet Extended S-Expression Notation.
      * 'json' outputs the same graph as 'pn' but with JSON syntax.

      The output will be "pretty printed" when the option --pretty is given together with --format 'pn' or 'json'.

View on GitHub (pinned to e227c27540)

Solutions

Scroll up to the per-template error output — it names the file, line, and parse problem
Re-run `puppet epp dump <file>` to get parser diagnostics for the failing template
Fix the unbalanced/invalid tags and re-validate
Add `puppet epp validate` (or `puppet parser validate`) to CI for module templates

Example fix

# before (bad.epp)
<% if $x { -%>value<% } %>    # invalid expression form
# after
<% if $x { -%>value<% } -%>
# then
puppet epp validate bad.epp

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Run `puppet epp validate` in CI for every template change
Prefer `puppet epp dump` while iterating — it exposes parse errors directly
Match every `<% if %>`/`<% unless %>` with `<% end %>` before saving

When it happens

Trigger: EPP files with unbalanced `<% if %>`/`<% end %>` tags, invalid Puppet expressions inside `<%= %>`, malformed parameter declaration blocks (`<%# parameters: ... -%>`); validating several files where one has a syntax error (the others still validate and report fine).

Common situations: Hand-editing templates without validating; upgrading Puppet versions where EPP parsing or parameter tags became stricter; ERB-to-EPP conversions done incompletely.

Related errors

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