fluent/fluentd · error · Fluent::ConfigError

chunk_keys specification includes invalid char

Error message

chunk_keys specification includes invalid char

What it means

A plain (non-accessor) chunk key contains characters outside `CHUNK_KEY_PATTERN = /^[-_.@a-zA-Z0-9]+$/`. Chunk keys become part of buffer chunk metadata (and often file paths), so Fluentd restricts them to letters, digits, `-`, `_`, `.`, and `@`. Anything else — spaces, slashes, `#`, unicode, leftover `$` — fails configuration.

Source

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

          @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
            if @timekey <= 0
              raise Fluent::ConfigError, "timekey should be greater than 0. current timekey: #{@timekey}"
            end
            @timekey_use_utc = @buffer_config.timekey_use_utc
            @offset = Fluent::Timezone.utc_offset(@timekey_zone)
            @calculate_offset = @offset.respond_to?(:call) ? @offset : nil
            @output_time_formatter_cache = {}
          end

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Rewrite the key to use only `[A-Za-z0-9_-.@]` characters
2. For nested fields, switch to dot-notation accessor form `$.a.b`, which is validated separately
3. Rename the record field upstream (record_transformer) if you cannot change the key

Example fix

# before
<buffer tenant id>
  @type file
</buffer>

# after
<buffer tenant,id>
  @type file
</buffer>

KEY_RE = /\A[-_.@a-zA-Z0-9]+\z/
keys = %w[tenant id]
invalid = keys.reject { |k| k.match?(KEY_RE) }
abort "invalid chunk key chars: #{invalid.join(', ')}" unless invalid.empty?
fluentd --dry-run -c /etc/fluent/fluent.conf

def valid_plain_chunk_key?(k)
  k.match?(%r{\A[-_.@a-zA-Z0-9]+\z})
end

When it happens

Trigger: `<buffer my key>` (embedded space from an unquoted list), `<buffer a/b>`, `<buffer key#1>`, or a key containing `$` that did not parse as a record accessor. The `k !~ CHUNK_KEY_PATTERN` check at output.rb:312 returns true and the error is raised.

Common situations: Splitting a comma/space separated list of keys incorrectly; pasting keys from spreadsheets or URLs (slashes, colons); locale-specific characters in key names.

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

• 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
• in chunk_keys: bracket notation is not allowed
• in chunk_keys: #{e.message}

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