🚨 Telegraf Error Guide: '[agent] flush_interval is not divisible / interval mismatch' — Fix Agent Timing

Overview

The [agent] section governs how often Telegraf collects (interval) and flushes (flush_interval). Misconfigured timing produces startup warnings and, worse, dropped metrics as buffers overflow. A common warning names the offending relationship:

2026-07-10T12:00:00Z W! [agent] flush_interval (30s) is larger than the collection interval (10s); metrics may accumulate and overflow the buffer

When collection itself runs long, the agent logs a gather timeout tied to the interval:

E! [agent] Collection took longer than expected; not complete after interval of 10s
W! [outputs.influxdb_v2] Metric buffer overflow; 500 metrics have been dropped

The visible failure is data loss: metrics are collected but silently dropped before they are written.

Symptoms

• Startup warnings about flush_interval, interval, or jitter in journalctl -u telegraf.
• Periodic Metric buffer overflow; N metrics have been dropped messages.
• Collection took longer than expected warnings when an input’s gather time exceeds interval.
• Sawtooth gaps in dashboards as buffers fill and dump.
• CPU/memory spikes on the Telegraf host from oversized buffers or too-frequent collection.

Common Root Causes

• flush_interval larger than interval with a small buffer — metrics pile up faster than they flush and overflow metric_buffer_limit.
• A slow input exceeding interval — an SNMP walk or exec script that takes longer than the collection interval, so cycles overlap and back up.
• metric_buffer_limit too small — the buffer cannot absorb a slow or briefly unavailable output.
• No flush_jitter — every output flushes at the same instant, spiking load and the destination.
• interval too aggressive — a 1s interval on hundreds of series overwhelms both agent and output.
• Per-plugin interval overrides that conflict with agent-level flushing assumptions.

Diagnostic Workflow

Start by reading the effective agent settings and any warnings at startup:

telegraf --config /etc/telegraf/telegraf.conf --test --debug 2>&1 | head -n 40
journalctl -u telegraf --since '15 min ago' | grep -iE 'flush|interval|overflow|dropped'

Measure how long each input actually takes to gather so you can size interval correctly. The internal input exposes this:

[[inputs.internal]]
  collect_memstats = true

The gather-time and buffer metrics then appear as internal_gather and internal_write series (gather_time_ns, metrics_dropped, buffer_size, buffer_limit).

A balanced agent section keeps flush_interval equal to or a divisor of interval, adds jitter, and sizes the buffer generously:

[agent]
  interval = "10s"          # how often inputs collect
  round_interval = true
  flush_interval = "10s"    # <= interval; flush at least as often as you collect
  flush_jitter = "3s"       # spread flushes to avoid thundering herd
  metric_batch_size = 1000
  metric_buffer_limit = 100000   # absorb slow/unavailable outputs
  collection_jitter = "2s"

For a slow input, give it its own longer interval instead of slowing the whole agent:

[[inputs.snmp]]
  interval = "60s"          # SNMP walk is slow; poll it less often
  agents = ["udp://10.0.0.1:161"]
  version = 2
  community = "${SNMP_COMMUNITY}"

Example Root Cause Analysis

A host logged Metric buffer overflow; metrics have been dropped every few minutes and dashboards showed sawtooth gaps. The agent had interval = "10s", flush_interval = "60s", and the default metric_buffer_limit = 10000. With ~2,000 series collected every 10s but flushed only every 60s, up to 12,000 metrics accumulated between flushes — more than the buffer could hold — so the oldest metrics were dropped on each cycle.

Two changes fixed it. First, flush_interval was lowered to 10s so flushing kept pace with collection. Second, metric_buffer_limit was raised to 100000 to absorb transient output slowness:

[agent]
  interval = "10s"
  flush_interval = "10s"
  flush_jitter = "3s"
  metric_buffer_limit = 100000

After the change, internal_write reported metrics_dropped = 0 and the sawtooth disappeared. The lesson: flush_interval should be no larger than interval, and metric_buffer_limit must be sized for how many metrics accumulate between flushes plus a safety margin for output hiccups.

Prevention Best Practices

• Keep flush_interval less than or equal to interval; flush at least as often as you collect.
• Size metric_buffer_limit for (series × intervals-between-flushes) plus headroom for a briefly unavailable output.
• Enable the internal input and alert on internal_write.metrics_dropped > 0 — dropped metrics are otherwise invisible.
• Give slow inputs (SNMP, exec, SQL) their own longer per-plugin interval rather than slowing the whole agent.
• Add flush_jitter and collection_jitter to avoid synchronized spikes across a fleet.
• Validate timing changes with telegraf --test --debug before rolling out, and watch startup warnings.

Quick Command Reference

# Show startup warnings about timing
telegraf --config /etc/telegraf/telegraf.conf --test --debug 2>&1 | head -n 40

# Watch for overflow / dropped-metric warnings live
journalctl -u telegraf -f | grep -iE 'overflow|dropped|interval'

# Inspect internal gather/write metrics (enable [[inputs.internal]])
telegraf --config /etc/telegraf/telegraf.conf --test --input-filter internal

# Confirm effective config
telegraf --version

Conclusion

Telegraf agent timing warnings and metric buffer overflow errors mean collection and flushing are out of balance: flush_interval is larger than interval, the buffer is too small, or a slow input exceeds its interval. Keep flush_interval <= interval, size metric_buffer_limit for the metrics that accumulate between flushes, give slow inputs their own interval, and monitor internal_write.metrics_dropped. Balanced timing turns silent data loss into a lossless, steady pipeline.