fluent/fluentd · error · Fluent::ConfigError

both of utc and localtime are specified, use only one of the

Error message

both of utc and localtime are specified, use only one of them

What it means

Fluent::ConfigError raised in TimeParameters#configure (lib/fluent/time.rb:172), included by parser/formatter plugins via Fluent::TimeParser::Parser mixin. It fires when the config explicitly sets BOTH localtime and utc and their boolean values agree (both true or both false, i.e. !(localtime ^ utc)). The two options are contradictory ways of choosing the clock, so fluentd refuses instead of guessing.

Source

Thrown at lib/fluent/time.rb:172

      end

      def configure(conf)
        if conf.has_key?('localtime') || conf.has_key?('utc')
          if conf.has_key?('localtime')
            conf['localtime'] = Fluent::Config.bool_value(conf['localtime'])
          elsif conf.has_key?('utc')
            conf['localtime'] = !(Fluent::Config.bool_value(conf['utc']))
            # Specifying "localtime false" means using UTC in TimeFormatter
            # And specifying "utc" is different from specifying "timezone +0000"(it's not always UTC).
            # There are difference between "Z" and "+0000" in timezone formatting.
            # TODO: add kwargs to TimeFormatter to specify "using localtime", "using UTC" or "using specified timezone" in more explicit way
          end
        end

        super

        if conf.has_key?('localtime') && conf.has_key?('utc') && !(@localtime ^ @utc)
          raise Fluent::ConfigError, "both of utc and localtime are specified, use only one of them"
        end

        if conf.has_key?('time_type') and @time_type == :mixed
          if @time_format.nil? and @time_format_fallbacks.empty?
            raise Fluent::ConfigError, "time_type is :mixed but time_format and time_format_fallbacks is empty."
          end
        end

        Fluent::Timezone.validate!(@timezone) if @timezone
      end
    end

    module Parser
      def self.included(mod)
        mod.include TimeParameters
      end

      def time_parser_create(type: @time_type, format: @time_format, timezone: @timezone, force_localtime: false)

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Keep only one option: use utc true for UTC, or localtime true/false for local time — delete the other key
2. If you need a fixed non-UTC offset, use timezone +0900 instead of either flag (requires a time format)
3. Audit the specific plugin section named in the error's config context — the check is per-parser-section, not global

Example fix

# before
<parse>
  @type apache2
  time_format %d/%b/%Y:%H:%M:%S %z
  localtime true
  utc true
</parse>

# after
<parse>
  @type apache2
  time_format %d/%b/%Y:%H:%M:%S %z
  utc true
</parse>

# pre-validate a parser section's time options:
keys = %w[localtime utc]
present = keys.select { |k| section_vars.key?(k) }
if present.size == 2
  lv = Fluent::Config.bool_value(section_vars['localtime'])
  uv = Fluent::Config.bool_value(section_vars['utc'])
  raise 'localtime and utc must not both be set to the same boolean' if lv == uv
end

When it happens

Trigger: A <parse> or <buffer> time section (or any plugin using time parameters) containing e.g. localtime true plus utc true, or localtime false plus utc false. Note the mixin rewrites conf['localtime'] from utc before super, so writing just utc is safe — only literal double specification trips the XOR check.

Common situations: Copy-pasting a parser config that had localtime and adding utc while refactoring timestamps to UTC; inheriting a default template with localtime false and then adding utc false believing it reinforces UTC; mixing tail parser settings from different documentation eras.

Related errors

• specifying timezone requires time format
• @type is required in <parse>
• duplicated parsers configured: #{section.usage}
• time_type is :mixed but time_format and time_format_fallback
• value must be string: #{value}

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