fluent/fluentd · error · Fluent::ConfigError

buffer path is not configured. specify 'path' in <buffer>

Error message

buffer path is not configured. specify 'path' in <buffer>

What it means

The file buffer plugin needs a storage location: either an explicit path in <buffer> or an implicit one derived from <system> root_dir plus the owning plugin's @id (owner.plugin_root_dir). When @path is nil and no plugin root dir exists, configure raises this ConfigError. The implicit path is preferred in multi-worker setups because it already contains the worker id.

Source

Thrown at lib/fluent/plugin/buf_file.rb:67

        @additional_resume_path = nil
        @buffer_path = nil
        @variable_store = nil
      end

      def configure(conf)
        super

        @variable_store = Fluent::VariableStore.fetch_or_build(:buf_file)

        multi_workers_configured = owner.system_config.workers > 1

        using_plugin_root_dir = false
        unless @path
          if root_dir = owner.plugin_root_dir
            @path = File.join(root_dir, 'buffer')
            using_plugin_root_dir = true # plugin_root_dir path contains worker id
          else
            raise Fluent::ConfigError, "buffer path is not configured. specify 'path' in <buffer>"
          end
        end

        type_of_owner = Plugin.lookup_type_from_class(@_owner.class)
        if @variable_store.has_key?(@path) && !called_in_test?
          type_using_this_path = @variable_store[@path]
          raise ConfigError, "Other '#{type_using_this_path}' plugin already use same buffer path: type = #{type_of_owner}, buffer path = #{@path}"
        end

        @buffer_path = @path
        @variable_store[@buffer_path] = type_of_owner

        specified_directory_exists = File.exist?(@path) && File.directory?(@path)
        unexisting_path_for_directory = !File.exist?(@path) && !@path.include?('.*')

        if specified_directory_exists || unexisting_path_for_directory # directory
          if using_plugin_root_dir || !multi_workers_configured
            @path = File.join(@path, "buffer.*#{@path_suffix}")

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Add an explicit path in the buffer section: <buffer>@type file</buffer> path /var/log/fluent/buffer (use a directory path or a 'prefix.*.suffix' pattern as documented)
2. Or provide the implicit location: give the output plugin an @id and set <system> root_dir /var/log/fluent </system> (recommended for multi-worker, since the path then includes the worker id)
3. Keep buffer paths unique per output to avoid the related 'already use same buffer path' error
4. Verify the buffer directory is writable by the fluentd user

Example fix

# before
<match demo.**>
  @type forward
  <buffer>
    @type file
  </buffer>
</match>

# after
<match demo.**>
  @type forward
  @id fwd_out
  <buffer>
    @type file
    path /var/log/fluent/buffer/fwd_out
  </buffer>
</match>

# In config generation, assert every file buffer has a location
conf.scan(/<buffer>(.*?)<\/buffer>/m).each do |body|
  next unless body.first.include?('@type file')
  abort 'file buffer without path' unless body.first.include?('path ') || conf.include?('root_dir')
end

When it happens

Trigger: <buffer>@type file</buffer> with no path, on an output whose plugin has no @id, and with no <system> root_dir set; configs ported from setups relying on a default that was never configured.

Common situations: First-time file-buffer configs omitting path; adding @type file buffers to existing outputs that lack @id; multi-worker deployments where per-worker storage via root_dir was intended but never declared.

Related errors

• this plugin '#{self.class}' cannot handle arguments for <buf
• this plugin '#{self.class}' allows <buffer tag> only
• time_slice_format only with %Y or %m is too long
• Other '#{type_using_this_path}' plugin already use same buff
• chunk keys must be tag or one field

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