puppetlabs/puppet · error · ArgumentError

PP syntax checker: the text to check must be a String.

Error message

PP syntax checker: the text to check must be a String.

What it means

The PP syntax-checker plugin validates Puppet Language text and requires the text argument to be a String. Passing a parsed AST model, Symbol, or nil raises ArgumentError before Puppet::Pops::Parser::EvaluatingParser.singleton.parse_string is ever called. The checker backs 'pp' syntax validation of heredocs/templates and is the same code path used for template content checks.

Source

Thrown at lib/puppet/syntax_checkers/pp.rb:18

# frozen_string_literal: true

# A syntax checker for JSON.
# @api public
require_relative '../../puppet/syntax_checkers'
class Puppet::SyntaxCheckers::PP < Puppet::Plugins::SyntaxCheckers::SyntaxChecker
  # Checks the text for Puppet Language syntax issues and reports them to the given acceptor.
  #
  # Error messages from the checker are capped at 100 chars from the source text.
  #
  # @param text [String] The text to check
  # @param syntax [String] The syntax identifier in mime style (only accepts 'pp')
  # @param acceptor [#accept] A Diagnostic acceptor
  # @param source_pos [Puppet::Pops::Adapters::SourcePosAdapter] A source pos adapter with location information
  # @api public
  #
  def check(text, syntax, acceptor, source_pos)
    raise ArgumentError, _("PP syntax checker: the text to check must be a String.") unless text.is_a?(String)
    raise ArgumentError, _("PP syntax checker: the syntax identifier must be a String, e.g. pp") unless syntax == 'pp'
    raise ArgumentError, _("PP syntax checker: invalid Acceptor, got: '%{klass}'.") % { klass: acceptor.class.name } unless acceptor.is_a?(Puppet::Pops::Validation::Acceptor)

    begin
      Puppet::Pops::Parser::EvaluatingParser.singleton.parse_string(text)
    rescue => e
      # Cap the message to 100 chars and replace newlines
      msg = _("PP syntax checker: \"%{message}\"") % { message: e.message().slice(0, 500).gsub(/\r?\n/, "\\n") }

      # TODO: improve the pops API to allow simpler diagnostic creation while still maintaining capabilities
      # and the issue code. (In this case especially, where there is only a single error message being issued).
      #
      issue = Puppet::Pops::Issues.issue(:ILLEGAL_PP) { msg }
      acceptor.accept(Puppet::Pops::Validation::Diagnostic.new(:error, issue, source_pos.file, source_pos, {}))
    end
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Guard for nil before calling: skip or raise your own descriptive error when text is nil
2. Pass the literal source string (File.read result, template body)
3. Type-check at your API boundary: fail fast with the received class in the message

Example fix

# before
checker.check(params[:code], 'pp', acceptor, pos) # params[:code] may be nil => ArgumentError

# after
code = params.fetch(:code)
raise ArgumentError, 'code is required' if code.nil?
checker.check(code, 'pp', acceptor, pos)

raise ArgumentError, 'manifest text is required' if text.nil?
raise ArgumentError, "text must be a String, got #{text.class}" unless text.is_a?(String)

When it happens

Trigger: Calling Puppet::SyntaxCheckers::PP.new.check(nil, 'pp', acceptor, source_pos), or forwarding a parsed object/AST instead of source text. Typical when tooling fetches manifest content that can be nil (missing file, empty lookup) and forwards it unchecked.

Common situations: Custom lint wrappers that read files which may not exist (IO#read on a closed handle, nil from an optional config key), or tests that pass fixture objects rather than raw strings.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• PP syntax checker: the syntax identifier must be a String, e
• PP syntax checker: invalid Acceptor, got: '%{klass}'.
• EPP syntax checker: invalid Acceptor, got: '%{klass}'.
• Json syntax checker: the text to check must be a String.
• Json syntax checker: the syntax identifier must be a String,

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