puppetlabs/puppet · error · Puppet::Pops::Types::StringConverter::FormatError

Illegal format '#{actual}' specified for value of Binary typ

Error message

Illegal format '#{actual}' specified for value of Binary type - expected one of the characters 'bButTsp'

What it means

StringConverter raises this FormatError when formatting a Binary value (Puppet::Pops::Types::PBinaryType — base64-wrapped byte data) with a conversion letter outside 'bButTsp': 'b' (base64), 'u' (URL-safe base64), 't'/'T' (the literal word 'Binary'/'BINARY', type-only output), 's'/'p' (string/quoted forms). The else at string_converter.rb:814 raises FormatError('Binary', f.format, 'bButTsp').

Source

Thrown at lib/puppet/pops/types/string_converter.rb:814

    when :b
      Kernel.format(f.orig_fmt.gsub('b', substitute), val.relaxed_to_s)

    when :B
      Kernel.format(f.orig_fmt.gsub('B', substitute), val.to_s)

    when :u
      Kernel.format(f.orig_fmt.gsub('u', substitute), val.urlsafe_to_s)

    when :t
      # Output as the type without any data
      Kernel.format(f.orig_fmt.gsub('t', substitute), 'Binary')

    when :T
      # Output as the type without any data in all caps
      Kernel.format(f.orig_fmt.gsub('T', substitute), 'BINARY')

    else
      raise FormatError.new('Binary', f.format, 'bButTsp')
    end
  end

  # @api private
  def string_PStringType(val_type, val, format_map, _)
    f = get_format(val_type, format_map)
    case f.format
    when :s
      Kernel.format(f.orig_fmt, val)

    when :p
      apply_string_flags(f, puppet_quote(val, f.alt?))

    when :c
      c_val = val.capitalize
      f.alt? ? apply_string_flags(f, puppet_quote(c_val)) : Kernel.format(f.orig_fmt.tr('c', 's'), c_val)

    when :C

View on GitHub (pinned to e227c27540)

Solutions

Use '%b' for base64 output or '%u' for URL-safe base64
Use '%s' only when the buffer is valid UTF-8 text (raw binary will produce broken strings)
Whitelist dynamic format letters against %w[b B u t T s p]

Example fix

# before
$str = String($blob, '%d')
# after
$str = String($blob, '%b')

Defensive patterns

Strategy: validation

Validate before calling

fmt = '%d'
letter = fmt[/\A%[#\-+ 0\d.]*([a-zA-Z])\z/, 1]
raise ArgumentError, "#{fmt} invalid for Binary" unless %w[b B u t T s p].include?(letter)

Prevention

Use %b/%u for base64 forms of Binary values
Never apply scalar formats to Binary blobs; convert deliberately (Base64 decode) first
Type-guard data pipelines so Binary never reaches generic formatters

When it happens

Trigger: `String(Binary('aGVsbG8='), '%d')`, `String($blob, '%x')` — any letter not in bButTsp applied to a Binary value; typically when generic numeric formats are applied to secrets/certificates/blobs stored as Binary via Binary()/Base64 decode.

Common situations: Handling PEM certs, DER keys or file contents loaded as Binary in tasks/plans; piping Binary into a shared formatting helper that assumes scalars; trying to hex-dump binary data with %x (not supported — use a dedicated function).

Related errors

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