fluent/fluentd · error · Fluent::ConfigError

Parameter '#{name}: #{string}' has tag placeholders, but chu

Error message

Parameter '#{name}: #{string}' has tag placeholders, but chunk key 'tag' is not configured

What it means

The parameter string contains `${tag}` or `${tag[N]}` placeholders but `tag` is not a buffer chunk key (`!tagkey && !parts.empty?` in `validate_tag!`). Without tag chunking there is no per-tag metadata to substitute, so the placeholder would be left as a literal string and the config is rejected instead.

Source

Thrown at lib/fluent/plugin/output.rb:750

          if !sec && timekey
            raise Fluent::ConfigError, "Parameter '#{name}: #{string}' doesn't have timestamp placeholders for timekey #{timekey.to_i}"
          end
          if sec && !timekey
            raise Fluent::ConfigError, "Parameter '#{name}: #{string}' has timestamp placeholders, but chunk key 'time' is not configured"
          end
          if sec && timekey && timekey < sec
            raise Fluent::ConfigError, "Parameter '#{name}: #{string}' doesn't have timestamp placeholder for #{title}('#{example}') for timekey #{timekey.to_i}"
          end
        end

        def validate_tag!
          parts = @argument[:parts]
          tagkey = @argument[:tagkey]
          if tagkey && parts.empty?
            raise Fluent::ConfigError, "Parameter '#{name}: #{string}' doesn't have tag placeholder"
          end
          if !tagkey && !parts.empty?
            raise Fluent::ConfigError, "Parameter '#{name}: #{string}' has tag placeholders, but chunk key 'tag' is not configured"
          end
        end

        def validate_keys!
          keys = @argument[:keys]
          chunk_keys = @argument[:chunkkeys]
          if (chunk_keys - keys).size > 0
            not_specified = (chunk_keys - keys).sort
            raise Fluent::ConfigError, "Parameter '#{name}: #{string}' doesn't have enough placeholders for keys #{not_specified.join(',')}"
          end
          if (keys - chunk_keys).size > 0
            not_satisfied = (keys - chunk_keys).sort
            raise Fluent::ConfigError, "Parameter '#{name}: #{string}' has placeholders, but chunk keys doesn't have keys #{not_satisfied.join(',')}"
          end
        end
      end

      TIME_KEY_PLACEHOLDER_THRESHOLDS = [

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Add `tag` to the chunk keys: `<buffer time,tag>` (timekey still required if `time` is present)
2. Or remove the `${tag}`/`${tag[N]}` placeholders from the parameter
3. If only part of the tag matters, chunk on tag anyway and reference `${tag[0]}` etc. in the path

Example fix

# before
<buffer time>
  timekey 1d
</buffer>
path /logs/${tag}/app.%Y%m%d.log

# after
<buffer time,tag>
  timekey 1d
</buffer>
path /logs/${tag}/app.%Y%m%d.log

fluentd --dry-run -c /etc/fluent/fluent.conf

When it happens

Trigger: `path /logs/${tag}.log` with `<buffer time>` or `<buffer tenant>` (tag not listed); any placeholder-validated parameter referencing ${tag} while the buffer chunks on something else.

Common situations: Removing `tag` from chunk keys while keeping a tag-templated path; using a path template copied from a per-tag example in an output chunked by a record field.

Related errors

• Parameter '#{name}: #{string}' doesn't have tag placeholder
• out_secondary_file: basename or directory has an incompatibl
• Parameter '#{name}: #{string}' doesn't have timestamp placeh
• Parameter '#{name}: #{string}' has timestamp placeholders, b
• Parameter '#{name}: #{string}' doesn't have timestamp placeh

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