fluent/fluentd · error · Fluent::ConfigError

2 or more chunk keys is not allowed

Error message

2 or more chunk keys is not allowed

What it means

In the file_single buffer's configure, after the tag case is excluded, chunk_keys.size > 1 raises this ConfigError: the single-file-per-chunk layout can encode only one record-field key in the path. Buffering on two or more fields (e.g. <buffer tenant, app>) is unsupported for this buffer type, unlike the standard file buffer which supports multiple chunk keys via path placeholders.

Source

Thrown at lib/fluent/plugin/buf_file_single.rb:75

      end

      def configure(conf)
        super

        @variable_store = Fluent::VariableStore.fetch_or_build(:buf_file_single)

        if @chunk_format == :auto
          @chunk_format = owner.formatted_to_msgpack_binary? ? :msgpack : :text
        end

        @key_in_path = nil
        if owner.chunk_keys.empty?
          log.debug "use event tag for buffer key"
        else
          if owner.chunk_key_tag
            raise Fluent::ConfigError, "chunk keys must be tag or one field"
          elsif owner.chunk_keys.size > 1
            raise Fluent::ConfigError, "2 or more chunk keys is not allowed"
          else
            @key_in_path = owner.chunk_keys.first.to_sym
          end
        end

        multi_workers_configured = owner.system_config.workers > 1
        using_plugin_root_dir = false
        unless @path
          if root_dir = owner.plugin_root_dir
            @path = File.join(root_dir, 'buffer')
            using_plugin_root_dir = true # plugin_root_dir path contains worker id
          else
            raise Fluent::ConfigError, "buffer path is not configured. specify 'path' in <buffer>"
          end
        end

        specified_directory_exists = File.exist?(@path) && File.directory?(@path)
        unexisting_path_for_directory = !File.exist?(@path) && !@path.include?('.*')

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Keep exactly one chunk key for file_single (<buffer tenant_id>)
2. Drop secondary keys if per-dimension files are not strictly required (filter/rewrite instead)
3. Switch to @type file (or memory) when multiple chunk keys are genuinely needed
4. Consider a separate label/match per dimension so each output owns a single-key buffer

Example fix

# before
<match demo.**>
  @type stdout
  <buffer tenant_id, user_id>
    @type file_single
  </buffer>
</match>

# after
<match demo.**>
  @type stdout
  <buffer tenant_id>
    @type file_single
  </buffer>
</match>

keys = buffer_keys - ['tag']
raise 'file_single: at most one chunk key allowed' if keys.size > 1

When it happens

Trigger: <buffer tenant_id, user_id>@type file_single</buffer>; two <key> entries in a file_single buffer; moving a multi-key file-buffer config to file_single unchanged.

Common situations: Partitioning outputs by multiple dimensions and choosing file_single for simplicity; performance tuning that switches buffer types without reviewing chunk keys.

Related errors

• chunk keys must be tag or one field
• this plugin '#{self.class}' cannot handle arguments for <buf
• this plugin '#{self.class}' allows <buffer tag> only
• time_slice_format only with %Y or %m is too long
• buffer path is not configured. specify 'path' in <buffer>

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