fluent/fluentd · error · Fluent::ConfigError

specifying timezone requires time format

Error message

specifying timezone requires time format

What it means

Fluent::ConfigError raised by Fluent::TimeParser#initialize (lib/fluent/time.rb:220) when a timezone (or utc/non-localtime mode) is requested but format is nil. Without an explicit strptime format there is no %z/%Z placeholder where the timezone could matter, so specifying timezone alone is meaningless and rejected.

Source

Thrown at lib/fluent/time.rb:220

        mod.include TimeParameters
      end

      def time_formatter_create(type: @time_type, format: @time_format, timezone: @timezone, force_localtime: false)
        return NumericTimeFormatter.new(type) if type != :string
        return TimeFormatter.new(format, true, nil) if force_localtime

        localtime = @localtime && (timezone.nil? && !@utc)
        TimeFormatter.new(format, localtime, timezone)
      end
    end
  end

  class TimeParser
    class TimeParseError < StandardError; end

    def initialize(format = nil, localtime = true, timezone = nil)
      if format.nil? && (timezone || !localtime)
        raise Fluent::ConfigError, "specifying timezone requires time format"
      end

      @cache1_key = nil
      @cache1_time = nil
      @cache2_key = nil
      @cache2_time = nil

      format_with_timezone = format && (format.include?("%z") || format.include?("%Z"))

      utc_offset = case
                   when format_with_timezone then
                     nil
                   when timezone then
                     Fluent::Timezone.utc_offset(timezone)
                   when localtime then
                     nil
                   else
                     0 # utc

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Set an explicit time_format that includes the timezone semantics you want, e.g. time_format %Y-%m-%dT%H:%M:%S%z together with the timezone option
2. Or remove the timezone / utc option if the default (EventTime or float) parsing is acceptable
3. Plugin developers: only pass timezone to Fluent::TimeParser.new when a format is also given

Example fix

# before
<parse>
  @type nginx
  timezone +0900
  # no time_format
</parse>

# after
<parse>
  @type nginx
  time_format %d/%b/%Y:%H:%M:%S %z
  timezone +0900
</parse>

format = nil
timezone = '+0900'
localtime = true
if format.nil? && (timezone || !localtime)
  raise 'timezone/utc requires an explicit time_format'
end

When it happens

Trigger: Constructing Fluent::TimeParser.new(nil, false, '+0900') directly, or configuring a plugin that passes timezone/utc while time_format is unset — e.g. <parse> with timezone +0000 but no time_format line. The condition is format.nil? && (timezone || !localtime).

Common situations: Adding timezone +0900 to a parser section assuming it applies to the default format; using in_tail/in_http parser configs where time_format was removed during cleanup but timezone stayed; plugin authors passing a timezone kwarg to TimeParser.new without a format.

Related errors

• both of utc and localtime are specified, use only one of the
• time_type is :mixed but time_format and time_format_fallback
• Unsupported timezone '#{timezone}'
• both of utc and localtime are specified, use only one of the
• @type is required in <parse>

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