fluent/fluentd · error · Fluent::ConfigError

chunk keys must be tag or one field

Error message

chunk keys must be tag or one field

What it means

The file_single buffer (registered as @type file_single) stores one file per chunk and encodes at most one routing key into the path: either the implicit event tag (empty <buffer/>) or a single record field. When 'tag' is listed together with another key (<buffer tag, app_id>), chunk_key_tag is true while chunk_keys is non-empty, and configure raises this ConfigError because the single-file naming scheme cannot encode both.

Source

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

        @additional_resume_path = nil
        @variable_store = nil
      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

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Use either the implicit tag (<buffer>@type file_single</buffer> with no keys) or exactly one field key (<buffer app_id>)
2. If you need tag plus fields or time-sliced chunking, switch back to @type file with an appropriate path pattern
3. Remove explicit <key>tag</key> entries — tag is already the default key when the key list is empty

Example fix

# before
<match demo.**>
  @type file_single
  <buffer tag, app_id>
    @type file_single
  </buffer>
</match>

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

# file_single accepts zero keys (implicit tag) or exactly one field key
keys = buffer_keys - ['tag']
raise 'file_single: use no keys or one field key, not tag + field' if buffer_keys.include?('tag') && !keys.empty?

When it happens

Trigger: <buffer tag, user_id>@type file_single</buffer>; listing <key>tag</key> plus another <key> in a file_single buffer section; converting a multi-key file-buffer config to file_single without dropping keys.

Common situations: Migrating from @type file (which supports richer keying) to file_single for lower overhead; tuning guides that suggest keying buffers by field while the config still includes tag.

Related errors

• 2 or more chunk keys is not allowed
• 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/ec9948ad2ae934b4. Report an issue: GitHub.