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

Illegal format '#{actual}' specified for value of URI type -

Error message

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

What it means

StringConverter raises this FormatError when formatting a Puppet URI value (PURIType, created by URI('...')) with a conversion letter other than 's' (plain to_s, Puppet-quoted with alt flag) or 'p' (TypeFormatter rendering, indentation-aware). The else at string_converter.rb:1130 raises FormatError('URI', f.format, 'sp'). This is the last member of the per-type format validation chain in string_converter.rb.

Source

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

    else
      raise FormatError.new('Type', f.format, 'sp')
    end
  end

  # @api private
  def string_PURIType(val_type, val, format_map, indentation)
    f = get_format(val_type, format_map)
    case f.format
    when :p
      fmt = TypeFormatter.singleton
      indentation = indentation.indenting(f.alt? || indentation.is_indenting?)
      fmt = fmt.indented(indentation.level, 2) if indentation.is_indenting?
      fmt.string(val)
    when :s
      str_val = val.to_s
      Kernel.format(f.orig_fmt, f.alt? ? puppet_quote(str_val) : str_val)
    else
      raise FormatError.new('URI', f.format, 'sp')
    end
  end

  # Maps the inferred type of o to a formatting rule
  def get_format(val_t, format_options)
    fmt = format_options.find { |k, _| k.assignable?(val_t) }
    return fmt[1] unless fmt.nil?

    Format.new("%s")
  end
  private :get_format
end
end
end

View on GitHub (pinned to e227c27540)

Solutions

Use '%s' for the plain URL string or '%p' for Puppet notation
If only string handling is needed, convert: String(String($url), $fmt) or keep URLs as plain Strings
Whitelist dynamic format letters against %w[s p]

Example fix

# before
$str = String($url, '%d')
# after
$str = String($url, '%s')

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Only %s and %p are valid for URI values
If URLs never need type-aware formatting, keep them as plain Strings instead of URI()
Watch inferred-type changes when upgrading validation from String to URI

When it happens

Trigger: `String(URI('https://x'), '%d')` or any non-s/p letter applied to a URI value; typically when URLs stored as URI-typed data are fed to a shared formatting helper with a scalar format.

Common situations: Formatting endpoint lists from Hiera that were parsed with URI(); report generation applying uniform formats to mixed data; migration from String-typed URLs to URI() validation which changes the inferred type and thus the legal format set.

Related errors

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