fluent/fluentd · error · Fluent::ConfigError

'tag' or 'tag_key' option is required on exec input

Error message

'tag' or 'tag_key' option is required on exec input

What it means

The exec input spawns a command and turns its stdout into events; every event needs a tag. After configure runs, in_exec checks that either the tag param is set or the <parse>/<extract> configuration yields a tag_key (a field of the parsed output to use as tag). When both are missing it raises Fluent::ConfigError "'tag' or 'tag_key' option is required on exec input", failing at config load.

Source

Thrown at lib/fluent/plugin/in_exec.rb:68

    desc 'The encoding to receive the result of the command, especially for non-ascii characters.'
    config_param :encoding, :string, default: nil

    attr_reader :parser

    def configure(conf)
      compat_parameters_convert(conf, :extract, :parser)
      ['parse', 'extract'].each do |subsection_name|
        if subsection = conf.elements(subsection_name).first
          if subsection.has_key?('time_format')
            subsection['time_type'] ||= 'string'
          end
        end
      end

      super

      if !@tag && (!@extract_config || !@extract_config.tag_key)
        raise Fluent::ConfigError, "'tag' or 'tag_key' option is required on exec input"
      end
      validate_encoding(@encoding) if @encoding
      @parser = parser_create
    end

    def validate_encoding(encoding)
      Encoding.find(encoding)
    rescue ArgumentError => e
      raise Fluent::ConfigError, e.message
    end

    def multi_workers_ready?
      true
    end

    def start
      super

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Add an explicit tag: tag exec.metrics in the <source>.
2. Or keep tag extraction from the command output by configuring the parse/extract subsection with tag_key <field>.
3. Validate the config with fluentd --dry-run.

Example fix

# before
<source>
  @type exec
  command /usr/local/bin/gen-metrics.sh
  run_interval 10s
  <parse>
    @type json
  </parse>
</source>
# after
<source>
  @type exec
  command /usr/local/bin/gen-metrics.sh
  run_interval 10s
  tag exec.metrics
  <parse>
    @type json
  </parse>
</source>

# config lint: exec input needs tag or tag_key
has_tag = conf =~ /^\s*tag\s+\S/
has_tag_key = conf =~ /tag_key/
abort "in_exec: set 'tag' or extract 'tag_key'" unless has_tag || has_tag_key
# authoritative: fluentd --dry-run -c /etc/fluent/fluent.conf

begin
  Fluent::Plugin.new_input('exec').configure(conf)
rescue Fluent::ConfigError => e
  abort "exec input config rejected: #{e.message}" # 'tag' or 'tag_key' option is required
end

When it happens

Trigger: An in_exec <source> with neither a tag param nor an extract tag_key (e.g. only <parse> @type json with no tag_key inside), so emitted events would have no tag.

Common situations: First-time exec input setups that copy a minimal example; switching from tag to tag_key extraction and accidentally removing both; refactors of the <parse> subsection dropping tag_key.

Related errors

• empty value is specified in fields parameter
• e.message
• Duplicate key in <or>: #{e.key}
• `renew_record` must be true to use `keep_keys`
• unknown_key

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