fluent/fluentd · error · Fluent::ConfigError

This plugin can only be used in the <secondary> section

Error message

This plugin can only be used in the <secondary> section

What it means

SecondaryFileOutput#configure raises this Fluent::ConfigError when the plugin is instantiated outside a `<secondary>` section — detected via the @as_secondary flag that Fluentd's output base sets only for plugins placed there. secondary_file exists solely to receive chunks the primary buffered output could not flush, so it has no standalone write semantics of its own.

Source

Thrown at lib/fluent/plugin/out_secondary_file.rb:40

module Fluent::Plugin
  class SecondaryFileOutput < Output
    Fluent::Plugin.register_output("secondary_file", self)

    PLACEHOLDER_REGEX = /\${(tag(\[\d+\])?|[\w.@-]+)}/

    desc "The directory path of the output file."
    config_param :directory, :string
    desc "The basename of the output file."
    config_param :basename, :string, default: "dump.bin"
    desc "The flushed chunk is appended to existence file or not."
    config_param :append, :bool, default: false
    config_param :compress, :enum, list: [:text, :gzip], default: :text

    def configure(conf)
      super

      unless @as_secondary
        raise Fluent::ConfigError, "This plugin can only be used in the <secondary> section"
      end

      if @basename.include?("/")
        raise Fluent::ConfigError, "basename should not include `/`"
      end

      @path_without_suffix = File.join(@directory, @basename)
      validate_compatible_with_primary_buffer!(@path_without_suffix)

      @suffix = case @compress
                when :text
                  ""
                when :gzip
                  ".gz"
                end

      test_path = @path_without_suffix
      unless Fluent::FileUtil.writable_p?(test_path)

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Nest it: use a real buffered primary (forward, http, s3, ...) and put `@type secondary_file` inside its `<secondary>` block
2. If you just want file output, use `@type file` with `path` instead
3. Validate nesting with `fluentd --dry-run`

Example fix

# before
<match debug.**>
  @type secondary_file
  directory /var/log/fluent/dump
</match>

# after
<match debug.**>
  @type forward
  <server> host 10.0.0.1 </server>
  <secondary>
    @type secondary_file
    directory /var/log/fluent/dump
  </secondary>
</match>

# Dry-run catches this at configure time
system('fluentd --dry-run -c fluent.conf') or abort 'invalid config'

# Structural check: secondary_file must only appear inside <secondary>
conf.elements.each do |match|
  next unless match.name == 'match'
  bad = match.elements.any? { |e| e.name != 'secondary' && e['@type'] == 'secondary_file' }
  raise 'secondary_file used outside <secondary>' if bad
end

When it happens

Trigger: Writing `<match **> @type secondary_file directory /var/log/dump </match>` as a primary output. Also triggered by copy/round-robin stores referencing secondary_file directly.

Common situations: Users wanting a plain 'dump to file' output and picking the similar-sounding secondary_file instead of @type file; copy-pasting a <secondary> block's contents up one level; fluentd docs examples trimmed too aggressively.

Related errors

• out_secondary_file: basename or directory has an incompatibl
• out_secondary_file: basename or directory has an incompatibl
• out_secondary_file: basename or directory has an incompatibl
• buffer path is not configured. specify 'path' in <buffer>
• basename should not include `/`

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