{"record":{"id":"18e5360287879330","repo":"fluent/fluentd","slug":"buffer-path-is-not-configured-specify-path-in-18e536","errorCode":null,"errorMessage":"buffer path is not configured. specify 'path' in <buffer>","messagePattern":"buffer path is not configured\\. specify 'path' in <buffer>","errorType":"exception","errorClass":"Fluent::ConfigError","httpStatus":null,"severity":"critical","filePath":"lib/fluent/plugin/buf_file_single.rb","lineNumber":88,"sourceCode":"          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\n        specified_directory_exists = File.exist?(@path) && File.directory?(@path)\n        unexisting_path_for_directory = !File.exist?(@path) && !@path.include?('.*')\n\n        if specified_directory_exists || unexisting_path_for_directory # directory\n          if using_plugin_root_dir || !multi_workers_configured\n            @path = File.join(@path, \"fsb.*#{PATH_SUFFIX}\")\n          else\n            @path = File.join(@path, \"worker#{fluentd_worker_id}\", \"fsb.*#{PATH_SUFFIX}\")\n            if fluentd_worker_id == 0\n              # worker 0 always checks unflushed buffer chunks to be resumed (might be created while non-multi-worker configuration)\n              @additional_resume_path = File.join(File.expand_path(\"../../\", @path), \"fsb.*#{PATH_SUFFIX}\")\n            end\n          end\n          @multi_workers_available = true\n        else # specified path is file path","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin/buf_file_single.rb#L70-L106","documentation":"Thrown by the file_single buffer plugin during configure when no buffer path can be determined. Fluent::Plugin::FileSingleBuffer requires either an explicit 'path' config param in the <buffer> section, or a plugin @id plus a system <root_dir> from which it derives <root_dir>/workerN/buffer. Without one of these it has nowhere to write chunk files and refuses to start with a Fluent::ConfigError.","triggerScenarios":"Configuring an output plugin with <buffer> @type file_single (or file) while omitting the path argument AND omitting the plugin's @id or the <system><root_dir> setting. The check runs in FileSingleBuffer#configure: unless @path is set, it falls back to owner.plugin_root_dir (only present when @id and root_dir are configured), and raises when that is also nil.","commonSituations":"Copying a file buffer config snippet that relied on a global root_dir that is absent in the new deployment; adding @type file_single to a new output tag without an @id; running fluentd with a minimal config where no <system> root_dir was ever defined; upgrading from v0.12 where paths defaulted differently.","solutions":["Add an explicit path to the buffer section: <buffer> @type file_single path /var/log/fluent/buffer </buffer>","Or give the output plugin a unique @id and set <system> root_dir /var/log/fluent </system> so the path becomes root_dir/workerN/plugin_id/buffer","Run fluentd --dry-run -c fluent.conf to catch this at deploy time instead of at runtime","Verify the fluentd user can create the target directory (permissions on the parent dir)"],"exampleFix":"# before\n<match app.**>\n  @type forward\n  <buffer>\n    @type file_single\n  </buffer>\n</match>\n\n# after\n<match app.**>\n  @type forward\n  @id forward_out\n  <buffer>\n    @type file_single\n    path /var/log/fluent/buffer/app\n  </buffer>\n</match>","handlingStrategy":"validation","validationCode":"# Validate the config before starting fluentd\nsystem('fluentd --dry-run -c /etc/fluent/fluent.conf')\n# exit status 0 means every buffer resolved a path; nonzero prints the ConfigError\n\n# Programmatic check when building a config:\nraise 'file_single buffer needs path or @id+root_dir' if\n  buffer[:type] == 'file_single' && buffer[:path].nil? &&\n  (plugin[:id].nil? || system_conf[:root_dir].nil?)","typeGuard":null,"tryCatchPattern":"begin\n  Fluent::Test::Driver::Output.new(MyOutput).configure(fluentd_conf)\nrescue Fluent::ConfigError => e\n  abort \"config invalid: #{e.message}\" if e.message.include?(\"buffer path is not configured\")\n  raise\nend","preventionTips":["Always set @id on outputs that use persistent buffers","Standardize on a <system> root_dir so paths are derived automatically","Make fluentd --dry-run part of the deploy pipeline","Never ship a <buffer> block with @type file_single and no path in templates lacking root_dir"],"tags":["fluentd","buffer","file-single","configuration","configerror"],"backgroundTag":"missing-config-parameter","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}