{"record":{"id":"c03a1527a963ab64","repo":"fluent/fluentd","slug":"specifying-timezone-requires-time-format","errorCode":null,"errorMessage":"specifying timezone requires time format","messagePattern":"specifying timezone requires time format","errorType":"exception","errorClass":"Fluent::ConfigError","httpStatus":null,"severity":"error","filePath":"lib/fluent/time.rb","lineNumber":220,"sourceCode":"        mod.include TimeParameters\n      end\n\n      def time_formatter_create(type: @time_type, format: @time_format, timezone: @timezone, force_localtime: false)\n        return NumericTimeFormatter.new(type) if type != :string\n        return TimeFormatter.new(format, true, nil) if force_localtime\n\n        localtime = @localtime && (timezone.nil? && !@utc)\n        TimeFormatter.new(format, localtime, timezone)\n      end\n    end\n  end\n\n  class TimeParser\n    class TimeParseError < StandardError; end\n\n    def initialize(format = nil, localtime = true, timezone = nil)\n      if format.nil? && (timezone || !localtime)\n        raise Fluent::ConfigError, \"specifying timezone requires time format\"\n      end\n\n      @cache1_key = nil\n      @cache1_time = nil\n      @cache2_key = nil\n      @cache2_time = nil\n\n      format_with_timezone = format && (format.include?(\"%z\") || format.include?(\"%Z\"))\n\n      utc_offset = case\n                   when format_with_timezone then\n                     nil\n                   when timezone then\n                     Fluent::Timezone.utc_offset(timezone)\n                   when localtime then\n                     nil\n                   else\n                     0 # utc","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/time.rb#L202-L238","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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","Or remove the timezone / utc option if the default (EventTime or float) parsing is acceptable","Plugin developers: only pass timezone to Fluent::TimeParser.new when a format is also given"],"exampleFix":"# before\n<parse>\n  @type nginx\n  timezone +0900\n  # no time_format\n</parse>\n\n# after\n<parse>\n  @type nginx\n  time_format %d/%b/%Y:%H:%M:%S %z\n  timezone +0900\n</parse>","handlingStrategy":"validation","validationCode":"format = nil\ntimezone = '+0900'\nlocaltime = true\nif format.nil? && (timezone || !localtime)\n  raise 'timezone/utc requires an explicit time_format'\nend","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Whenever you set timezone or utc on a parser, set time_format in the same edit","Plugin authors: guard Fluent::TimeParser.new calls — only pass timezone when format is non-nil"],"tags":["fluentd","configuration","time","timezone","parser","startup"],"backgroundTag":"invalid-configuration","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}