What causes "Could not render to %{format}: %{err}" in puppetlabs/puppet?

Render with the class default: obj.render (no argument) uses default_format from supported_formats.

puppetlabs/puppet · error · Puppet::Network::FormatHandler::FormatError

Could not render to %{format}: %{err}

Error message

Could not render to %{format}: %{err}

What it means

Instance-level FormatSupport#render wraps failures from format.render(self) into FormatError 'Could not render to %{format}: %{err}'. The wrapped error is usually an unknown format (get_format raising ArgumentError), a missing to_* method (NotImplementedError), or an exception inside the model's own serializer such as to_data_hash hitting nil state.

Source

Thrown at lib/puppet/network/format_support.rb:116

    to_data_hash.to_msgpack(*args)
  end

  # @deprecated, use to_json
  def to_pson(*args)
    to_data_hash.to_pson(*args)
  end

  def to_json(*args)
    Puppet::Util::Json.dump(to_data_hash, *args)
  end

  def render(format = nil)
    format ||= self.class.default_format

    self.class.get_format(format).render(self)
  rescue => err
    # TRANSLATORS "render" is a function name and should not be translated
    raise Puppet::Network::FormatHandler::FormatError, _("Could not render to %{format}: %{err}") % { format: format, err: err }, err.backtrace
  end

  def mime(format = nil)
    format ||= self.class.default_format

    self.class.get_format(format).mime
  rescue => err
    # TRANSLATORS "mime" is a function name and should not be translated
    raise Puppet::Network::FormatHandler::FormatError, _("Could not mime to %{format}: %{err}") % { format: format, err: err }, err.backtrace
  end

  def support_format?(name)
    self.class.support_format?(name)
  end

  # @comment Document to_data_hash here as it is called as a hook from to_msgpack if it exists
  # @!method to_data_hash(*args)
  # @api public

View on GitHub (pinned to e227c27540)

Solutions

Render with the class default: obj.render (no argument) uses default_format from supported_formats.
Fix the to_data_hash failure named in %{err} — usually nil handling.
Load the optional gem (msgpack) on every node that must render that format.
Whitelist caller-provided format names against obj.class.supported_formats.

Example fix

# before
payload = report.render(params[:format]) # FormatError when params[:format] is unsupported

# after
allowed = report.class.supported_formats.map(&:to_s)
fmt = allowed.include?(params[:format]) ? params[:format] : report.class.default_format
payload = report.render(fmt)

Defensive patterns

Strategy: validation

Validate before calling

fmt = Widget.supported_formats.include?(requested.to_sym) ? requested.to_sym : Widget.default_format
payload = widget.render(fmt)

Try / catch

begin
  widget.render(fmt)
rescue Puppet::Network::FormatHandler::FormatError => e
  # %{err} names the cause; retry with the default format
  widget.render
end

Prevention

Prefer default_format unless a specific format is required.
Validate externally sourced format names against supported_formats.
Make to_data_hash total — handle nils explicitly.
Load serialization gems consistently across the fleet.

When it happens

Trigger: obj.render(:msgpack) without msgpack support; obj.render(:bogus) (never registered); rendering an object whose to_data_hash raises on nil fields or bad encoding.

Common situations: Custom faces and handlers serializing partially built objects; format names taken straight from request parameters; optional gems absent on one node of the fleet.

Related errors

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