{"record":{"id":"ec9948ad2ae934b4","repo":"fluent/fluentd","slug":"chunk-keys-must-be-tag-or-one-field","errorCode":null,"errorMessage":"chunk keys must be tag or one field","messagePattern":"chunk keys must be tag or one field","errorType":"exception","errorClass":"Fluent::ConfigError","httpStatus":null,"severity":"error","filePath":"lib/fluent/plugin/buf_file_single.rb","lineNumber":73,"sourceCode":"        @additional_resume_path = nil\n        @variable_store = nil\n      end\n\n      def configure(conf)\n        super\n\n        @variable_store = Fluent::VariableStore.fetch_or_build(:buf_file_single)\n\n        if @chunk_format == :auto\n          @chunk_format = owner.formatted_to_msgpack_binary? ? :msgpack : :text\n        end\n\n        @key_in_path = nil\n        if owner.chunk_keys.empty?\n          log.debug \"use event tag for buffer key\"\n        else\n          if owner.chunk_key_tag\n            raise Fluent::ConfigError, \"chunk keys must be tag or one field\"\n          elsif owner.chunk_keys.size > 1\n            raise Fluent::ConfigError, \"2 or more chunk keys is not allowed\"\n          else\n            @key_in_path = owner.chunk_keys.first.to_sym\n          end\n        end\n\n        multi_workers_configured = owner.system_config.workers > 1\n        using_plugin_root_dir = false\n        unless @path\n          if root_dir = owner.plugin_root_dir\n            @path = File.join(root_dir, 'buffer')\n            using_plugin_root_dir = true # plugin_root_dir path contains worker id\n          else\n            raise Fluent::ConfigError, \"buffer path is not configured. specify 'path' in <buffer>\"\n          end\n        end\n","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin/buf_file_single.rb#L55-L91","documentation":"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.","triggerScenarios":"<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.","commonSituations":"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.","solutions":["Use either the implicit tag (<buffer>@type file_single</buffer> with no keys) or exactly one field key (<buffer app_id>)","If you need tag plus fields or time-sliced chunking, switch back to @type file with an appropriate path pattern","Remove explicit <key>tag</key> entries — tag is already the default key when the key list is empty"],"exampleFix":"# before\n<match demo.**>\n  @type file_single\n  <buffer tag, app_id>\n    @type file_single\n  </buffer>\n</match>\n\n# after\n<match demo.**>\n  @type file_single\n  <buffer app_id>\n    @type file_single\n  </buffer>\n</match>","handlingStrategy":"validation","validationCode":"# file_single accepts zero keys (implicit tag) or exactly one field key\nkeys = buffer_keys - ['tag']\nraise 'file_single: use no keys or one field key, not tag + field' if buffer_keys.include?('tag') && !keys.empty?","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use <buffer/> (tag implicit) or <buffer one_field> with @type file_single","Need richer keying? stay on @type file","Drop explicit <key>tag</key> from file_single configs"],"tags":["fluentd","buffer","file-single-buffer","chunk-keys","config"],"backgroundTag":"invalid-buffer-config","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}