{"record":{"id":"56e49b169fe04870","repo":"fluent/fluentd","slug":"this-plugin-can-only-be-used-in-the-secondary-se","errorCode":null,"errorMessage":"This plugin can only be used in the <secondary> section","messagePattern":"This plugin can only be used in the <secondary> section","errorType":"validation","errorClass":"Fluent::ConfigError","httpStatus":null,"severity":"error","filePath":"lib/fluent/plugin/out_secondary_file.rb","lineNumber":40,"sourceCode":"module Fluent::Plugin\n  class SecondaryFileOutput < Output\n    Fluent::Plugin.register_output(\"secondary_file\", self)\n\n    PLACEHOLDER_REGEX = /\\${(tag(\\[\\d+\\])?|[\\w.@-]+)}/\n\n    desc \"The directory path of the output file.\"\n    config_param :directory, :string\n    desc \"The basename of the output file.\"\n    config_param :basename, :string, default: \"dump.bin\"\n    desc \"The flushed chunk is appended to existence file or not.\"\n    config_param :append, :bool, default: false\n    config_param :compress, :enum, list: [:text, :gzip], default: :text\n\n    def configure(conf)\n      super\n\n      unless @as_secondary\n        raise Fluent::ConfigError, \"This plugin can only be used in the <secondary> section\"\n      end\n\n      if @basename.include?(\"/\")\n        raise Fluent::ConfigError, \"basename should not include `/`\"\n      end\n\n      @path_without_suffix = File.join(@directory, @basename)\n      validate_compatible_with_primary_buffer!(@path_without_suffix)\n\n      @suffix = case @compress\n                when :text\n                  \"\"\n                when :gzip\n                  \".gz\"\n                end\n\n      test_path = @path_without_suffix\n      unless Fluent::FileUtil.writable_p?(test_path)","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin/out_secondary_file.rb#L22-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Nest it: use a real buffered primary (forward, http, s3, ...) and put `@type secondary_file` inside its `<secondary>` block","If you just want file output, use `@type file` with `path` instead","Validate nesting with `fluentd --dry-run`"],"exampleFix":"# before\n<match debug.**>\n  @type secondary_file\n  directory /var/log/fluent/dump\n</match>\n\n# after\n<match debug.**>\n  @type forward\n  <server> host 10.0.0.1 </server>\n  <secondary>\n    @type secondary_file\n    directory /var/log/fluent/dump\n  </secondary>\n</match>","handlingStrategy":"validation","validationCode":"# Dry-run catches this at configure time\nsystem('fluentd --dry-run -c fluent.conf') or abort 'invalid config'\n\n# Structural check: secondary_file must only appear inside <secondary>\nconf.elements.each do |match|\n  next unless match.name == 'match'\n  bad = match.elements.any? { |e| e.name != 'secondary' && e['@type'] == 'secondary_file' }\n  raise 'secondary_file used outside <secondary>' if bad\nend","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember the rule: secondary_file lives ONLY inside <secondary>; for plain file output use @type file","Keep a reviewed example of a correct <match>+<secondary> skeleton in your config repo","Dry-run all configs in CI so section-misuse never reaches a running agent"],"tags":["fluentd","secondary-file","buffer","configuration","plugin-misuse"],"backgroundTag":"plugin-section-misuse","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}