fluent/fluentd · error · Fluent::ConfigError

'flush_interval' can't be specified when 'flush_mode' is not

Error message

'flush_interval' can't be specified when 'flush_mode' is not 'interval' explicitly: '#{@flush_mode}'

What it means

`flush_interval` only takes effect when `flush_mode` is `interval`; Fluentd makes it a hard error if `flush_interval` is set while `flush_mode` is explicitly set to something else (`lazy`, `periodic`). If `flush_mode` were left at its default this would only be a warning — the raise happens specifically when you wrote both options and they contradict.

Source

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

                                 else
                                   true # flush_at_shutdown is true in default for on-memory buffer
                                 end
          elsif !@flush_at_shutdown && !@buffer.persistent?
            buf_type = Plugin.lookup_type_from_class(@buffer.class)
            log.warn "'flush_at_shutdown' is false, and buffer plugin '#{buf_type}' is not persistent buffer."
            log.warn "your configuration will lose buffered data at shutdown. please confirm your configuration again."
          else
            if Fluent.windows? && @buffer.persistent?
              service_timeout = read_wait_to_kill_service_timeout
              if service_timeout && service_timeout <= 5000 # default value might varies on windows client/server
                log.warn "your WaitToKillServiceTimeout=#{service_timeout} registry configuration seems too short. Recommend to extend the value of 'HKLM\\SYSTEM\\CurrentControlSet\\Control\\WaitToKillServiceTimeout' to prevent buffer corruption from a forced shutdown"
              end
            end
          end

          if (@flush_mode != :interval) && buffer_conf.has_key?('flush_interval')
            if buffer_conf.has_key?('flush_mode')
              raise Fluent::ConfigError, "'flush_interval' can't be specified when 'flush_mode' is not 'interval' explicitly: '#{@flush_mode}'"
            else
              log.warn "'flush_interval' is ignored because default 'flush_mode' is not 'interval': '#{@flush_mode}'"
            end
          end

          if @buffer.queued_chunks_limit_size.nil?
            @buffer.queued_chunks_limit_size = @buffer_config.flush_thread_count
          end
        end

        if @secondary_config
          raise Fluent::ConfigError, "Invalid <secondary> section for non-buffered plugin" unless @buffering
          raise Fluent::ConfigError, "<secondary> section cannot have <buffer> section" if @secondary_config.buffer
          raise Fluent::ConfigError, "<secondary> section cannot have <secondary> section" if @secondary_config.secondary
          if @buffer_config.retry_forever
            log.warn "<secondary> with 'retry_forever', only unrecoverable errors are moved to secondary"
          end

View on GitHub (pinned to dd45c6e18d)

Solutions

Remove `flush_interval` when using `flush_mode lazy` or `periodic`
Or set `flush_mode interval` if interval flushing is what you want
For periodic-style behavior use `flush_thread_interval`/`flush_thread_burst_interval` instead of mixing modes

Example fix

# before
<buffer tag>
  @type file
  flush_mode lazy
  flush_interval 5s
</buffer>

# after
<buffer tag>
  @type file
  flush_mode lazy
</buffer>

Defensive patterns

Strategy: validation

Validate before calling

fluentd --dry-run -c /etc/fluent/fluent.conf
# lint: flag any buffer block containing both flush_mode (non-interval) and flush_interval

Prevention

flush_interval belongs only with flush_mode interval (or default mode)
When switching flush modes, grep the config for leftover flush_interval
Know the pairs: lazy uses chunk limits, periodic uses flush_thread_interval, interval uses flush_interval

When it happens

Trigger: A buffer block containing both `flush_mode lazy` (or `periodic`) and `flush_interval 5s`. The check `(@flush_mode != :interval) && buffer_conf.has_key?('flush_interval')` combined with `buffer_conf.has_key?('flush_mode')` at output.rb:387-390 raises during configure.

Common situations: Editing an existing config that used interval flushing to lazy mode but leaving `flush_interval` behind; merging config snippets from different docs; CI catching this only after a fluentd upgrade tightened the warning into an error.

Related errors

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