fluent/fluentd · error · Fluent::ConfigError

<buffer ...> argument includes 'time', but timekey is not co

Error message

<buffer ...> argument includes 'time', but timekey is not configured

What it means

The buffer section lists `time` as a chunk key but no `timekey` was configured. `timekey` defines the time window (e.g. 1h) over which records are grouped into one chunk, and it is mandatory whenever `time` chunking is used — without it Fluentd cannot compute chunk boundaries or expand time placeholders.

Source

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

                  k !~ CHUNK_KEY_PATTERN
                else
                  if key.start_with?('$[')
                    raise Fluent::ConfigError, "in chunk_keys: bracket notation is not allowed"
                  else
                    false
                  end
                end
              rescue => e
                raise Fluent::ConfigError, "in chunk_keys: #{e.message}"
              end
            }
            raise Fluent::ConfigError, "chunk_keys specification includes invalid char"
          else
            @chunk_key_accessors = Hash[@chunk_keys.map { |key| [key.to_sym, Fluent::PluginHelper::RecordAccessor::Accessor.new(key)] }]
          end

          if @chunk_key_time
            raise Fluent::ConfigError, "<buffer ...> argument includes 'time', but timekey is not configured" unless @buffer_config.timekey
            Fluent::Timezone.validate!(@buffer_config.timekey_zone)
            @timekey_zone = @buffer_config.timekey_use_utc ? '+0000' : @buffer_config.timekey_zone
            @timekey = @buffer_config.timekey
            if @timekey <= 0
              raise Fluent::ConfigError, "timekey should be greater than 0. current timekey: #{@timekey}"
            end
            @timekey_use_utc = @buffer_config.timekey_use_utc
            @offset = Fluent::Timezone.utc_offset(@timekey_zone)
            @calculate_offset = @offset.respond_to?(:call) ? @offset : nil
            @output_time_formatter_cache = {}
          end

          if (@chunk_key_tag ? 1 : 0) + @chunk_keys.size >= CHUNKING_FIELD_WARN_NUM
            log.warn "many chunk keys specified, and it may cause too many chunks on your system."
          end

          # no chunk keys or only tags (chunking can be done without iterating event stream)
          @simple_chunking = !@chunk_key_time && @chunk_keys.empty?

View on GitHub (pinned to dd45c6e18d)

Solutions

  1. Add a `timekey` to the buffer section matching the granularity you need (e.g. `timekey 1h`)
  2. Add `timekey_zone` if records must be bucketed in a local timezone
  3. Keep `time` in chunk keys only if you actually want time-based rotation; otherwise remove it

Example fix

# before
<buffer time>
  @type file
</buffer>

# after
<buffer time>
  @type file
  timekey 1h
  timekey_zone +09:00
</buffer>
Defensive patterns

Strategy: validation

Validate before calling

fluentd --dry-run -c /etc/fluent/fluent.conf
# quick lint: every '<buffer ...time' block needs a timekey line in the same section

Prevention

When it happens

Trigger: `<buffer time>` with no `timekey` line in the same buffer block. The check `unless @buffer_config.timekey` at output.rb:330 fires during `#configure` of any buffered output (file, s3, forward with time key, etc.).

Common situations: Users copy a time-chunked `<buffer>` example but trim the `timekey` line; migration from v0.12 `time_slice_format`-based configs where the format string implied the window; adding `time` while editing a tag-keyed buffer.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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