fluent/fluentd · error · Fluent::ConfigError

in chunk_keys: bracket notation is not allowed

Error message

in chunk_keys: bracket notation is not allowed

What it means

Fluentd parses each `<buffer ...>` chunk key with RecordAccessor and rejects bracket-notation accessors (`$[...]`, e.g. `$[0]` or `$['key']`) for chunk keys, even though the record_accessor helper itself supports them. Only bare field names and dot notation (`$.a.b`) may be used to group records into chunks. Bracket accessors would make chunk keys ambiguous and expensive to compute per record.

Source

Thrown at lib/fluent/plugin/output.rb:315

          if !@buffering && !@buffering.nil?
            raise Fluent::ConfigError, "secondary plugin '#{self.class}' must support buffering, but doesn't"
          end
        end

        if (@buffering || @buffering.nil?) && !@as_secondary
          # When @buffering.nil?, @buffer_config was initialized with default value for all parameters.
          # If so, this configuration MUST success.
          @chunk_keys = @buffer_config.chunk_keys.dup
          @chunk_key_time = !!@chunk_keys.delete('time')
          @chunk_key_tag = !!@chunk_keys.delete('tag')
          if @chunk_keys.any? { |key|
              begin
                k = Fluent::PluginHelper::RecordAccessor::Accessor.parse_parameter(key)
                if k.is_a?(String)
                  k !~ CHUNK_KEY_PATTERN
                else
                  if key.start_with?('$[')
                    raise Fluent::ConfigError, "in chunk_keys: bracket notation is not allowed"
                  else
                    false
                  end
                end
              rescue => e
                raise Fluent::ConfigError, "in chunk_keys: #{e.message}"
              end
            }
            raise Fluent::ConfigError, "chunk_keys specification includes invalid char"
          else
            @chunk_key_accessors = Hash[@chunk_keys.map { |key| [key.to_sym, Fluent::PluginHelper::RecordAccessor::Accessor.new(key)] }]
          end

          if @chunk_key_time
            raise Fluent::ConfigError, "<buffer ...> argument includes 'time', but timekey is not configured" unless @buffer_config.timekey
            Fluent::Timezone.validate!(@buffer_config.timekey_zone)
            @timekey_zone = @buffer_config.timekey_use_utc ? '+0000' : @buffer_config.timekey_zone
            @timekey = @buffer_config.timekey

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Chunk on a hash field using dot notation instead: `<buffer $.hostname>`
2. Expose the array element as a normal field upstream with `record_transformer`, then chunk on that field
3. Chunk on a stable bare key (e.g. `<buffer tenant>`) if the value is at the record top level

Example fix

# before
<buffer $[0]>
  @type file
</buffer>

# after (flatten upstream, then chunk on a real field)
<filter **>
  @type record_transformer
  <record>
    hostname ${record['hosts'][0]}
  </record>
</filter>
<buffer $.hostname>
  @type file
</buffer>

# Reject bracket-notation chunk keys before deploy
keys = %w[$[0] $.tenant tenant]
bad = keys.select { |k| k.start_with?('$[') }
abort "bracket notation not allowed: #{bad.join(', ')}" unless bad.empty?
fluentd --dry-run -c /etc/fluent/fluent.conf

def valid_chunk_key?(k)
  !k.start_with?('$[') && (k == k[/\A[\w.\-@]+\z/] || k.start_with?('$.') || k.start_with?('$[') == false)
end

When it happens

Trigger: A buffer section like `<buffer $[0]>`, `<buffer $['tenant']>` or `<buffer $.tags[0]>`... specifically any chunk key string whose parsed form is an accessor and which starts with `$[`. Configure-time check `key.start_with?('$[')` raises immediately.

Common situations: Developers try to chunk on an array element of the record (first tag, first label) and reach for the bracket syntax the record_accessor docs show; also happens when a key is built dynamically from user data containing `$[`.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• in chunk_keys: #{e.message}
• chunk keys must be tag or one field
• 2 or more chunk keys is not allowed
• out_secondary_file: basename or directory has an incompatibl
• chunk_keys specification includes invalid char

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