fluent/fluentd · error · Fluent::ConfigError

Parameter '#{name}: #{string}' doesn't have tag placeholder

Error message

Parameter '#{name}: #{string}' doesn't have tag placeholder

What it means

The buffer chunks on `tag` (`tag` in chunk keys, so `tagkey` is truthy) but the parameter string contains no `${tag}` or `${tag[N]}` placeholder. All tag-keyed chunks would collapse to the same value, so `validate_tag!` (`tagkey && parts.empty?`) rejects the configuration.

Source

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

          title = @argument[:title]
          example = @argument[:example]
          timekey = @argument[:timekey]
          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

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Add `${tag}` (or an indexed part like `${tag[0]}`) to the parameter: `path /logs/${tag}/app.log`
2. Or drop `tag` from the chunk keys if per-tag files are not intended
3. Use `${tag[1]}`-style parts when only a segment of the dotted tag should form the path

Example fix

# before
<buffer tag>
  @type file
</buffer>
path /logs/app.log

# after
<buffer tag>
  @type file
</buffer>
path /logs/${tag}/app.log

fluentd --dry-run -c /etc/fluent/fluent.conf
# lint: buffer chunk key 'tag' requires ${tag} (or ${tag[N]}) in the path

When it happens

Trigger: `<buffer tag>` with `path /logs/app.log` in a file output, or a `file`/`s3` `path` lacking `${tag}` while the buffer section chunks on tag; fires for any parameter run through `placeholder_validate!` where tag chunking is on but no tag placeholder appears.

Common situations: Adding `tag` to chunk keys to separate logs per tag but forgetting to put `${tag}` in the path; renaming the path to a constant during debugging while keeping tag chunking enabled.

Related errors

• Parameter '#{name}: #{string}' has tag placeholders, but chu
• 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/298ba623f510fe1f. Report an issue: GitHub.