puppetlabs/puppet · error · ArgumentError

I don't know how to render '%{format}'

Error message

I don't know how to render '%{format}'

What it means

FaceBase#render_as= resolves the requested output format through Puppet::Network::FormatHandler.format; an unknown name yields nil and ArgumentError 'I don't know how to render' fires. Only formats registered with FormatHandler (before this assignment) are selectable as render targets.

Source

Thrown at lib/puppet/application/face_base.rb:36

  end

  option("--help", "-h") do |_arg|
    if action && !@is_default_action
      # Only invoke help on the action if it was specified, not if
      # it was the default action.
      puts Puppet::Face[:help, :current].help(face.name, action.name)
    else
      puts Puppet::Face[:help, :current].help(face.name)
    end
    exit(0)
  end

  attr_reader :render_as
  attr_accessor :face, :action, :type, :arguments

  def render_as=(format)
    @render_as = Puppet::Network::FormatHandler.format(format)
    @render_as or raise ArgumentError, _("I don't know how to render '%{format}'") % { format: format }
  end

  def render(result, args_and_options)
    hook = action.when_rendering(render_as.name)

    if hook
      # when defining when_rendering on your action you can optionally
      # include arguments and options
      if hook.arity > 1
        result = hook.call(result, *args_and_options)
      else
        result = hook.call(result)
      end
    end

    render_as.render(result)
  end

View on GitHub (pinned to e227c27540)

Solutions

1. List what is available: Puppet::Network::FormatHandler.supported_formats (json, yaml, s, console, ...) and use one of those
2. Fix the typo in the --render_as value
3. If a custom format is genuinely required, register it with Puppet::Network::FormatHandler.create before render_as is assigned

Example fix

# before
puppet module list --render_as yml   # unregistered name

# after
puppet module list --render_as yaml

fmt = 'yaml'
raise ArgumentError, "unknown render format #{fmt}" unless Puppet::Network::FormatHandler.format(fmt)
app.render_as = fmt

When it happens

Trigger: Passing --render_as with a typo'd or unregistered name ('yml' instead of 'yaml', 'yolo'); code setting app.render_as = 'custom' where the registering plugin/gem is not loaded; format names that differ across puppet versions.

Common situations: Scripts assuming a format name from an older puppet version; custom output formats provided by a face/plugin that is not installed on the node; automation piping puppet face output into tools expecting a specific serializer.

Related errors

• puppet %{face} %{action} takes %{arg_count} argument, but yo
• #{instance.class} does not respond to #{render_method}; can
• %{klass} does not respond to %{method}; can not render multi
• Could not render_multiple to %{format}: %{err}
• Could not render to %{format}: %{err}

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