fluent/fluentd · error · Fluent::ConfigError

'format' parameter is required

Error message

'format' parameter is required

What it means

Raised as Fluent::ConfigError by the legacy compatibility helper Fluent::Compat::TextFormatter.create(conf), which builds a formatter from a v0.12-style conf. It selects the plugin purely via conf['format']; when that key is nil there is nothing to instantiate and configuration aborts with "'format' parameter is required".

Source

Thrown at lib/fluent/compat/formatter.rb:61

          Fluent::Plugin.register_formatter(type, Proc.new { ProcWrappedFormatter.new(template) })
        elsif template.respond_to?(:call)
          Fluent::Plugin.register_formatter(type, template)
        else
          raise ArgumentError, "Template for formatter must be a Class or callable object"
        end
      end

      def self.lookup(type)
        # TODO: warn when deprecated to use Plugin.new_formatter(type, parent: plugin)
        Fluent::Plugin.new_formatter(type)
      end

      # Keep backward-compatibility
      def self.create(conf)
        # TODO: warn when deprecated
        format = conf['format']
        if format.nil?
          raise ConfigError, "'format' parameter is required"
        end

        formatter = lookup(format)
        if formatter.respond_to?(:configure)
          formatter.configure(conf)
        end
        formatter
      end

      HandleTagAndTimeMixin = Fluent::Compat::HandleTagAndTimeMixin
      StructuredFormatMixin = Fluent::Compat::StructuredFormatMixin

      class ProcWrappedFormatter < Fluent::Plugin::ProcWrappedFormatter
        # TODO: warn when deprecated
      end

      class OutFileFormatter < Fluent::Plugin::OutFileFormatter
        # TODO: warn when deprecated

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Set the format key in the conf passed to create: { 'format' => 'json', ... }
2. Map '@type' to 'format' before calling create when translating v1 configs
3. Prefer the v1 API: Fluent::Plugin.new_formatter(type).configure(conf) or Fluent::Compat::TextFormatter.lookup(type)

Example fix

# before
formatter = Fluent::Compat::TextFormatter.create('output_format' => 'json')

# after
formatter = Fluent::Compat::TextFormatter.create('format' => 'json')

conf['format'] = conf.delete('@type') if conf['format'].nil? && conf['@type']
raise 'conf needs a format key' if conf['format'].nil?
formatter = Fluent::Compat::TextFormatter.create(conf)

begin
  Fluent::Compat::TextFormatter.create(conf)
rescue Fluent::ConfigError => e
  raise unless e.message.include?("'format' parameter is required")
  conf = conf.merge('format' => 'json') # sensible default, then retry
  retry
end

When it happens

Trigger: TextFormatter.create(conf) where conf only has keys like 'out_format' or '@type'; v0.12 plugin code migrated to v1 where the type now lives in '@type' instead of 'format'; programmatically built conf hashes that forgot the format key.

Common situations: Old plugins calling TextFormatter.create on user-supplied config sections; config translations from v0.12 ('format json') to v1 ('@type json'); test drivers passing minimal confs.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Missing '@type' parameter on <#{e.name}> directive
• Template for formatter must be a Class or callable object
• both of utc and localtime are specified, use only one of the
• this plugin '#{self.class}' cannot handle arguments for <buf
• this plugin '#{self.class}' allows <buffer tag> only

AI-assisted analysis of fluent/fluentd@dd45c6e18d (2026-08-21). Data as JSON: /api/errors/b7af051028ad55c8. Report an issue: GitHub.