fluent/fluentd · error · Fluent::ConfigError

duplicated formatter configured: #{section.usage}

Error message

duplicated formatter configured: #{section.usage}

What it means

Fluent::ConfigError raised while the Formatter helper's configure processes @formatter_configs. Each <format> section is stored in @_formatters keyed by its usage label (the name in <format mylabel>, or '' when unlabelled). A second section with the same usage would silently overwrite the first formatter instance, so configure fails fast naming the duplicated usage.

Source

Thrown at lib/fluent/plugin_helper/formatter.rb:87

      def self.included(mod)
        mod.include FormatterParams
      end

      attr_reader :_formatters # for tests

      def initialize
        super
        @_formatters_started = false
        @_formatters = {} # usage => formatter
      end

      def configure(conf)
        super

        @formatter_configs.each do |section|
          if @_formatters[section.usage]
            raise Fluent::ConfigError, "duplicated formatter configured: #{section.usage}"
          end
          formatter = Plugin.new_formatter(section[:@type], parent: self)
          formatter.configure(section.corresponding_config_element)
          @_formatters[section.usage] = formatter
        end
      end

      def start
        super
        @_formatters_started = true
        @_formatters.each_pair do |usage, formatter|
          formatter.start
        end
      end

      def formatter_operate(method_name, &block)
        @_formatters.each_pair do |usage, formatter|
          begin

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Give each <format> section a unique label such as <format json_fmt> and <format ltsv_fmt>, then select them in code with formatter_create(usage: 'json_fmt')
2. Delete the accidentally duplicated <format> block if only one formatter is intended

Example fix

# before
<match app.**>
  @type stdout
  <format>
    @type json
  </format>
  <format>
    @type ltsv
  </format>
</match>

# after
<match app.**>
  @type stdout
  <format json_fmt>
    @type json
  </format>
  <format ltsv_fmt>
    @type ltsv
  </format>
</match>

# detect duplicate usage before configure runs
usages = @formatter_configs.map(&:usage)
if usages.uniq.size != usages.size
  dup = usages.find { |u| usages.count(u) > 1 }
  raise Fluent::ConfigError, "duplicate <format> label: #{dup.inspect}"
end

When it happens

Trigger: Two <format> sections in one plugin block whose labels collide: two bare <format> sections (both usage '') or two <format access_log> sections. The raise happens during plugin #configure, before start.

Common situations: Copy-pasting a <format> block when adding a second formatter and forgetting to give the copies distinct labels; assuming multiple unlabelled <format> sections accumulate.

Related errors

• @type is required in <format>
• duplicated parsers configured: #{section.usage}
• <system> is duplicated. <system> should be only one
• unknown_key
• Template for formatter must be a Class or callable object

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