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

Illegal format '#{actual}' specified for value of Integer ty

Error message

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

What it means

StringConverter raises this FormatError when formatting an Integer with a conversion letter outside 'dxXobBeEfgGaAspc'. Integers accept numeric radix and float letters (dxXobBeEfgGaA), string/inspect forms (s/p) and character output (c). Any other letter — notably '%v' (n/a, only legal for Undef) or '%t' — falls through to the else at string_converter.rb:749 and raises FormatError('Integer', f.format, 'dxXobBeEfgGaAspc').

Source

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

    case f.format
    when :d, :x, :X, :o, :b, :B, :p
      Kernel.format(f.orig_fmt, val)

    when :e, :E, :f, :g, :G, :a, :A
      Kernel.format(f.orig_fmt, val.to_f)

    when :c
      char = [val].pack("U")
      char = f.alt? ? "\"#{char}\"" : char
      Kernel.format(f.orig_fmt.tr('c', 's'), char)

    when :s
      fmt = f.alt? ? 'p' : 's'
      int_str = Kernel.format('%d', val)
      Kernel.format(f.orig_fmt.gsub('s', fmt), int_str)

    else
      raise FormatError.new('Integer', f.format, 'dxXobBeEfgGaAspc')
    end
  end

  # @api private
  def string_PFloatType(val_type, val, format_map, _)
    f = get_format(val_type, format_map)
    case f.format
    when :d, :x, :X, :o, :b, :B
      Kernel.format(f.orig_fmt, val.to_i)

    when :e, :E, :f, :g, :G, :a, :A, :p
      Kernel.format(f.orig_fmt, val)

    when :s
      float_str = f.alt? ? "\"#{Kernel.format('%p', val)}\"" : Kernel.format('%p', val)
      Kernel.format(f.orig_fmt, float_str)

    else

View on GitHub (pinned to e227c27540)

Solutions

Use '%d' (decimal), '%x'/'%o'/'%b' (radix), '%e'/'%f'/'%g' (float forms) or '%s' for integers
If you want sprintf semantics, call sprintf() directly instead of String(value, fmt)
Validate dynamic format letters against %w[d x X o b B e E f g G a A s p c]

Example fix

# before
$str = String($count, '%v')
# after
$str = String($count, '%d')

Defensive patterns

Strategy: validation

Validate before calling

fmt = '%v'
letter = fmt[/\A%[#\-+ 0\d.]*([a-zA-Z])\z/, 1]
raise ArgumentError, "#{fmt} invalid for Integer" unless %w[d x X o b B e E f g G a A s p c].include?(letter)

Prevention

Default to %d for integers; use sprintf() when you want full printf semantics
Keep per-type format maps instead of a single shared format string
Reject %v/%t style letters from external format sources for numeric fields

When it happens

Trigger: `String(42, '%v')`, `String($count, '%t')`, `String(10, '%q')` — conversion letter not in the allowed set. Frequently hit by passing a full printf spec meant for sprintf into String() where the letter must match the value's Puppet type.

Common situations: Copy-pasting sprintf format strings between contexts; formatting mixed-type structure values with one shared format; data-driven format strings from Hiera containing a letter valid for a different type.

Related errors

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