puppetlabs/puppet · error · ArgumentError

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

Error message

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

What it means

The JSON syntax-checker plugin (lib/puppet/syntax_checkers/json.rb) validates raw JSON text and reports issues to an acceptor. Its contract requires the text argument to be a String; anything else (a parsed Hash, Symbol, Pathname, IO) raises ArgumentError immediately. The checker is registered under the 'json' key in Puppet::Plugins and is invoked when Puppet validates heredoc/template content tagged with json syntax.

Source

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

# frozen_string_literal: true

# A syntax checker for JSON.
# @api public
require_relative '../../puppet/syntax_checkers'
class Puppet::SyntaxCheckers::Json < Puppet::Plugins::SyntaxCheckers::SyntaxChecker
  # Checks the text for JSON 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 (e.g. 'json', 'json-patch+json', 'xml', 'myapp+xml'
  # @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, _("Json syntax checker: the text to check must be a String.") unless text.is_a?(String)
    raise ArgumentError, _("Json syntax checker: the syntax identifier must be a String, e.g. json, data+json") unless syntax.is_a?(String)
    raise ArgumentError, _("Json syntax checker: invalid Acceptor, got: '%{klass}'.") % { klass: acceptor.class.name } unless acceptor.is_a?(Puppet::Pops::Validation::Acceptor)

    begin
      Puppet::Util::Json.load(text)
    rescue => e
      # Cap the message to 100 chars and replace newlines
      msg = _("JSON syntax checker: Cannot parse invalid JSON string. \"%{message}\"") % { message: e.message().slice(0, 100).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_JSON) { 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. Pass the raw source string: File.read(path) or the template text exactly as produced
2. If the value came from JSON.parse, go back to the original string or call .to_json only for output, never for checking
3. Add a guard: raise ArgumentError, 'expected String' unless text.is_a?(String) before invoking the checker

Example fix

# before
parsed = JSON.parse(raw)
checker.check(parsed, 'json', acceptor, pos) # => ArgumentError

# after
checker.check(raw, 'json', acceptor, pos)

raise ArgumentError, "text must be a String, got #{text.class}" unless text.is_a?(String)

def string?(v)
  v.is_a?(String)
end

begin
  checker.check(text, 'json', acceptor, pos)
rescue ArgumentError => e
  raise ArgumentError, "JSON checker input invalid: #{e.message}"
end

When it happens

Trigger: Calling Puppet::SyntaxCheckers::Json.new.check(hash, 'json', acceptor, source_pos) where hash is an already-parsed JSON object, a Symbol, or nil. Typical in tooling that does JSON.parse(text) and then forwards the result instead of the original string.

Common situations: Custom validation pipelines that parse-then-check, passing File objects or Pathname instead of File.read output, or spec helpers that pass fixtures loaded via YAML/JSON helpers 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

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

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