fluent/fluentd · critical · 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

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.

Source

Thrown at lib/fluent/plugin/buf_file_single.rb:88

          log.debug "use event tag for buffer key"
        else
          if owner.chunk_key_tag
            raise Fluent::ConfigError, "chunk keys must be tag or one field"
          elsif owner.chunk_keys.size > 1
            raise Fluent::ConfigError, "2 or more chunk keys is not allowed"
          else
            @key_in_path = owner.chunk_keys.first.to_sym
          end
        end

        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

        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, "fsb.*#{PATH_SUFFIX}")
          else
            @path = File.join(@path, "worker#{fluentd_worker_id}", "fsb.*#{PATH_SUFFIX}")
            if fluentd_worker_id == 0
              # worker 0 always checks unflushed buffer chunks to be resumed (might be created while non-multi-worker configuration)
              @additional_resume_path = File.join(File.expand_path("../../", @path), "fsb.*#{PATH_SUFFIX}")
            end
          end
          @multi_workers_available = true
        else # specified path is file path

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Add an explicit path to the buffer section: <buffer> @type file_single path /var/log/fluent/buffer </buffer>
2. 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
3. Run fluentd --dry-run -c fluent.conf to catch this at deploy time instead of at runtime
4. Verify the fluentd user can create the target directory (permissions on the parent dir)

Example fix

# before
<match app.**>
  @type forward
  <buffer>
    @type file_single
  </buffer>
</match>

# after
<match app.**>
  @type forward
  @id forward_out
  <buffer>
    @type file_single
    path /var/log/fluent/buffer/app
  </buffer>
</match>

# Validate the config before starting fluentd
system('fluentd --dry-run -c /etc/fluent/fluent.conf')
# exit status 0 means every buffer resolved a path; nonzero prints the ConfigError

# Programmatic check when building a config:
raise 'file_single buffer needs path or @id+root_dir' if
  buffer[:type] == 'file_single' && buffer[:path].nil? &&
  (plugin[:id].nil? || system_conf[:root_dir].nil?)

begin
  Fluent::Test::Driver::Output.new(MyOutput).configure(fluentd_conf)
rescue Fluent::ConfigError => e
  abort "config invalid: #{e.message}" if e.message.include?("buffer path is not configured")
  raise
end

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Other '#{type_using_this_path}' plugin already uses same buf
• regexp#{i} does not contain 2 parameters
• regexp#{i} contains a duplicated key, #{key}
• exclude#{i} does not contain 2 parameters
• exclude#{i} contains a duplicated key, #{key}

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