fluent/fluentd · error · Fluent::ConfigError

whitespace character is not allowed in dot notation. Use bra

Error message

whitespace character is not allowed in dot notation. Use bracket notation: #{key}

What it means

Fluent::ConfigError from Fluent::RecordAccessor's validate_dot_keys. In dot notation each path segment must be free of whitespace (checked with /\s+/), because a key containing spaces cannot be expressed unambiguously in dot form. The message tells you to switch to bracket notation for that key.

Source

Thrown at lib/fluent/plugin_helper/record_accessor.rb:123

          keys.each { |key|
            if key.include?('[')
              result.concat(parse_dot_array_op(key, param))
            else
              result << key
            end
          }

          raise Fluent::ConfigError, "empty keys in dot notation" if result.empty?
          validate_dot_keys(result)

          result
        end

        def self.validate_dot_keys(keys)
          keys.each { |key|
            next unless key.is_a?(String)
            if /\s+/.match?(key)
              raise Fluent::ConfigError, "whitespace character is not allowed in dot notation. Use bracket notation: #{key}"
            end
          }
        end

        def self.parse_dot_array_op(key, param)
          start = key.index('[')
          result = if start.zero?
                     []
                   else
                     [key[0..start - 1]]
                   end
          key = key[start + 1..-1]
          in_bracket = true

          until key.empty?
            if in_bracket
              if i = key.index(']')
                index_value = key[0..i - 1]

View on GitHub (pinned to dd45c6e18d)

Solutions

Switch the offending key to bracket notation: $['my key'] instead of $.my key
Strip or normalize keys before composing dot-notation paths
Check for invisible trailing/leading whitespace in the config value (the message includes the offending key)

Example fix

# before
accessor = record_accessor_create('$.my key')

# after
accessor = record_accessor_create("$['my key']")

Defensive patterns

Strategy: validation

Validate before calling

# reject whitespace before Fluent does, and switch to bracket form
keys = param[2..-1].split('.')
if keys.any? { |k| k.match?(%r{\s}) }
  param = "$['#{keys.join('.')}']"
end
accessor = record_accessor_create(param)

Try / catch

begin
  record_accessor_create(param)
rescue Fluent::ConfigError => e
  param = param.gsub(/\s+/, '_')
  retry_count ||= 0
  (retry_count += 1) < 2 ? retry : raise
end

Prevention

Prefer bracket notation whenever keys originate outside your code
Strip whitespace from keys before composing paths
Quote any key that can contain spaces: $['my key']]

When it happens

Trigger: record_accessor_create with a dot-notation path whose key contains whitespace: $.my key, $.log level, or a trailing/leading space like $.foo .

Common situations: Record keys derived from log field names, HTTP headers or user-supplied labels that contain spaces; copy-pasting a key with an invisible trailing space into a config value.

Related errors

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