{"record":{"id":"88882fec2306776e","repo":"fluent/fluentd","slug":"in-chunk-keys-bracket-notation-is-not-allowed","errorCode":null,"errorMessage":"in chunk_keys: bracket notation is not allowed","messagePattern":"in chunk_keys: bracket notation is not allowed","errorType":"validation","errorClass":"Fluent::ConfigError","httpStatus":null,"severity":"error","filePath":"lib/fluent/plugin/output.rb","lineNumber":315,"sourceCode":"          if !@buffering && !@buffering.nil?\n            raise Fluent::ConfigError, \"secondary plugin '#{self.class}' must support buffering, but doesn't\"\n          end\n        end\n\n        if (@buffering || @buffering.nil?) && !@as_secondary\n          # When @buffering.nil?, @buffer_config was initialized with default value for all parameters.\n          # If so, this configuration MUST success.\n          @chunk_keys = @buffer_config.chunk_keys.dup\n          @chunk_key_time = !!@chunk_keys.delete('time')\n          @chunk_key_tag = !!@chunk_keys.delete('tag')\n          if @chunk_keys.any? { |key|\n              begin\n                k = Fluent::PluginHelper::RecordAccessor::Accessor.parse_parameter(key)\n                if k.is_a?(String)\n                  k !~ CHUNK_KEY_PATTERN\n                else\n                  if key.start_with?('$[')\n                    raise Fluent::ConfigError, \"in chunk_keys: bracket notation is not allowed\"\n                  else\n                    false\n                  end\n                end\n              rescue => e\n                raise Fluent::ConfigError, \"in chunk_keys: #{e.message}\"\n              end\n            }\n            raise Fluent::ConfigError, \"chunk_keys specification includes invalid char\"\n          else\n            @chunk_key_accessors = Hash[@chunk_keys.map { |key| [key.to_sym, Fluent::PluginHelper::RecordAccessor::Accessor.new(key)] }]\n          end\n\n          if @chunk_key_time\n            raise Fluent::ConfigError, \"<buffer ...> argument includes 'time', but timekey is not configured\" unless @buffer_config.timekey\n            Fluent::Timezone.validate!(@buffer_config.timekey_zone)\n            @timekey_zone = @buffer_config.timekey_use_utc ? '+0000' : @buffer_config.timekey_zone\n            @timekey = @buffer_config.timekey","sourceCodeStart":297,"sourceCodeEnd":333,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin/output.rb#L297-L333","documentation":"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.","triggerScenarios":"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.","commonSituations":"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 `$[`.","solutions":["Chunk on a hash field using dot notation instead: `<buffer $.hostname>`","Expose the array element as a normal field upstream with `record_transformer`, then chunk on that field","Chunk on a stable bare key (e.g. `<buffer tenant>`) if the value is at the record top level"],"exampleFix":"# before\n<buffer $[0]>\n  @type file\n</buffer>\n\n# after (flatten upstream, then chunk on a real field)\n<filter **>\n  @type record_transformer\n  <record>\n    hostname ${record['hosts'][0]}\n  </record>\n</filter>\n<buffer $.hostname>\n  @type file\n</buffer>","handlingStrategy":"validation","validationCode":"# Reject bracket-notation chunk keys before deploy\nkeys = %w[$[0] $.tenant tenant]\nbad = keys.select { |k| k.start_with?('$[') }\nabort \"bracket notation not allowed: #{bad.join(', ')}\" unless bad.empty?\nfluentd --dry-run -c /etc/fluent/fluent.conf","typeGuard":"def valid_chunk_key?(k)\n  !k.start_with?('$[') && (k == k[/\\A[\\w.\\-@]+\\z/] || k.start_with?('$.') || k.start_with?('$[') == false)\nend","tryCatchPattern":null,"preventionTips":["Chunk only on hash fields; flatten array values upstream with record_transformer","Lint buffer sections for `$[` in keys","Use dry-run to catch it at deploy time, not at 3am"],"tags":["fluentd","buffer","chunk-keys","record-accessor"],"backgroundTag":"config-validation-failed","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}