🚨 Telegraf Error Guide: 'did not complete within its flush interval' — Fix Slow Output Flushes

Overview

Telegraf flushes each output on a fixed cadence set by flush_interval. If an output’s Write() call takes longer than that interval to complete, the agent logs a warning and the next flush cycle is already waiting:

2026-07-11T12:00:00Z W! [agent] ["outputs.influxdb"] did not complete within its flush interval

This means the destination is not draining metrics as fast as Telegraf is trying to hand them over. Left alone, the per-output buffer backs up, and once it hits metric_buffer_limit the oldest metrics are dropped. The warning is an early signal that write latency — not collection — is your bottleneck.

Symptoms

• Repeated did not complete within its flush interval warnings for one or more outputs.
• Rising write_time_ns in the internal plugin metrics for that output.
• Buffer pressure climbing (buffer_size approaching buffer_limit), sometimes followed by Metric buffer overflow.
• Dashboards for that destination lag real time or show intermittent gaps.
• One slow output (a remote/DR endpoint) dragging down an otherwise healthy agent.

Common Root Causes

• Slow destination — the output endpoint is CPU-saturated, I/O-bound, or over a high-latency WAN link, so each batch write takes seconds.
• timeout longer than flush_interval — a slow write is allowed to run past the flush cadence instead of failing fast.
• metric_batch_size too large — each flush ships a huge batch the destination can’t absorb inside the interval.
• High-cardinality writes — unbounded tags make the destination’s indexing slow, inflating write time.
• A shared/DR output on a slower path is not isolated, so its latency stalls the whole flush cycle.
• Undersized destination — the target store is simply under-provisioned for the ingest rate.

How to diagnose

Find which output is slow and how long its writes take. Enable the internal plugin and read write_time_ns:

[[inputs.internal]]
  collect_memstats = true

telegraf --config /etc/telegraf/telegraf.conf --test --input-filter internal \
  | grep -E 'write_time_ns|buffer_size|buffer_limit|metrics_dropped'

Correlate the warning with the specific output in the logs:

journalctl -u telegraf --since '15 min ago' \
  | grep -iE 'did not complete|flush interval|write_time|overflow'

Measure the destination’s actual write latency directly, independent of Telegraf:

curl -o /dev/null -s -w 'http=%{http_code} time=%{time_total}s\n' \
  -XPOST "http://influxdb:8086/write?db=telemetry" --data-binary 'probe value=1'

A time_total in the seconds range confirms the destination — not Telegraf — is the bottleneck.

Fixes

1. Make the output fail fast — align timeout with flush_interval. A write should never be allowed to run longer than the flush cadence:

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

[[outputs.influxdb]]
  urls = ["http://influxdb:8086"]
  database = "telemetry"
  timeout = "5s"          # < flush_interval, so a stalled write aborts and retries

2. Shrink the batch so each write fits inside the interval. If a 5,000-metric batch takes 12s, halve it:

[agent]
  metric_batch_size = 500   # smaller batches drain within flush_interval

3. Isolate a slow/DR output so its latency can’t stall the healthy one. Give the slow destination its own generous buffer and route only what it needs:

[[outputs.influxdb]]
  urls = ["http://influxdb-primary:8086"]
  database = "telemetry"
  timeout = "5s"

[[outputs.influxdb]]
  urls = ["http://influxdb-dr:8086"]
  database = "telemetry"
  timeout = "5s"
  metric_buffer_limit = 200000   # absorb the slower path independently
  [outputs.influxdb.tagpass]
    keep = ["dr"]

4. Cut write latency at the source — control cardinality:

[[processors.tag_limit]]
  limit = 10
  keep = ["host", "region", "service"]

5. If the destination is genuinely undersized, scale it (more CPU/IOPS, sharding) or move to a durable queue output so Telegraf isn’t blocked on synchronous writes.

What to watch out for

• Setting timeout >= flush_interval reintroduces the problem — the write must be able to abort before the next flush.
• Simply raising metric_buffer_limit hides the warning but delays the eventual overflow; fix write latency first.
• A slow output without isolation can pin memory and back-pressure the whole agent — always separate a known-slow destination.
• Alert on internal_write.write_time_ns and metrics_dropped > 0, not just on the log line, so slowdowns surface before drops start.
• Very small batches increase request overhead; tune batch size against the destination’s throughput, don’t just minimize it.

Related

• Telegraf agent timing / flush interval mismatch
• metric buffer overflow — dropped metrics on a full buffer
• error writing to outputs — could not write

More fixes in the Telegraf guides.