🚨 Telegraf Error Guide: 'invalid data format: <name>' — Fix the Input Parser

Overview

Every input that ingests arbitrary payloads (exec, file, tail, http, kafka_consumer, mqtt_consumer, and more) needs a data_format telling Telegraf how to parse the bytes into metrics. When data_format names a parser Telegraf does not have, it refuses to start and names the bad value:

E! error loading config file /etc/telegraf/telegraf.conf: invalid data format: jsonv2

The same class of error appears when a parser is spelled or cased wrong, or when a required parser sub-table is missing:

E! [inputs.file] creating parser: undefined data format: "prometheus_text"

Because this is a configuration/startup failure, the agent does not begin collecting until the format name is valid.

Symptoms

• Telegraf fails to start with invalid data format / undefined data format naming the value you set.
• systemctl status telegraf shows a restart loop right after a config edit that added or changed data_format.
• The format name looks almost right but is misspelled, mis-cased, or uses an old alias.
• A json_v2/csv/grok parser is selected but its required sub-table is missing, so parsing produces nothing.
• Data that clearly is JSON or Prometheus is being read as line protocol because data_format was never set (defaults to influx).

Common Root Causes

• Typo or wrong casing — jsonv2 instead of json_v2, Prometheus instead of prometheus, csv_v2 (does not exist).
• Using an unsupported/renamed parser — a name from another tool or an old Telegraf version that was renamed.
• Missing parser sub-table — data_format = "json_v2" without a [[inputs.x.json_v2]] block, or grok without grok_patterns.
• Wrong parser for the payload — pointing influx at JSON, or json_v2 at Prometheus text.
• Format name from documentation of a newer release — the parser exists upstream but not in the installed binary.
• Copy-paste of an output data_format into an input (or vice versa) where the name is not valid on that side.

Diagnostic Workflow

First confirm the intended format is a real, supported parser by testing a minimal config for that input. Telegraf validates data_format at parse time, so --test fails fast on a bad name:

telegraf --config /etc/telegraf/telegraf.conf --test 2>&1 | grep -i 'data format'
telegraf --version    # cross-check the parser exists in this release

Isolate the input with a file payload to iterate on the parser without live sources:

# /tmp/format-test.conf
[[inputs.file]]
  files = ["/tmp/sample.json"]
  data_format = "json_v2"
  [[inputs.file.json_v2]]
    measurement_name = "api"
    [[inputs.file.json_v2.field]]
      path = "queue.depth"
      type = "int"

[[outputs.file]]
  files = ["stdout"]

printf '{"queue":{"depth":42}}\n' > /tmp/sample.json
telegraf --config /tmp/format-test.conf --test

Match the parser to the payload. Common valid values and their required companions:

# Prometheus exposition text — no sub-table needed
[[inputs.http]]
  urls = ["http://127.0.0.1:9273/metrics"]
  data_format = "prometheus"

# CSV — requires column configuration
[[inputs.file]]
  files = ["/var/log/app/metrics.csv"]
  data_format = "csv"
  csv_header_row_count = 1
  csv_timestamp_column = "ts"
  csv_timestamp_format = "unix"

# Grok for unstructured logs — requires patterns
[[inputs.tail]]
  files = ["/var/log/nginx/access.log"]
  data_format = "grok"
  grok_patterns = ['%{COMBINED_LOG_FORMAT}']

Example Root Cause Analysis

An engineer added an HTTP scrape of a service’s JSON stats endpoint and Telegraf crash-looped with invalid data format: jsonv2. They had written data_format = "jsonv2", but the correct parser name is json_v2 (with an underscore). Telegraf validates the name against its registered parser set at startup, found no jsonv2, and aborted before collecting anything.

Correcting the name and adding the required sub-table fixed it:

[[inputs.http]]
  urls = ["http://127.0.0.1:8080/stats"]
  data_format = "json_v2"
  [[inputs.http.json_v2]]
    measurement_name = "app_stats"
    [[inputs.http.json_v2.field]]
      path = "connections.active"
      type = "int"

After the edit, telegraf --test --input-filter http printed app_stats metrics. The broader lesson: parser names are exact identifiers (json_v2, prometheus, csv, grok, influx, xpath_json, …) and several require a matching sub-table; verify the spelling against the installed version and always test with a sample payload.

Prevention Best Practices

• Use exact, lowercase, underscore-form parser names and verify them against telegraf --version and the matching docs for that release.
• Pair each parser with its required companion config: json_v2 sub-table, grok_patterns, or CSV column settings.
• Test the parser against a representative sample via a file input and telegraf --test before deploying.
• Never leave data_format unset on a non-line-protocol source; the default influx will misparse JSON/CSV/Prometheus.
• Keep parser configuration in one drop-in per source so a bad format name is isolated and easy to bisect.
• On upgrades, re-check that any parser you rely on still exists and has not been renamed.

Quick Command Reference

# Fail-fast validation surfaces a bad data_format name
telegraf --config /etc/telegraf/telegraf.conf --test 2>&1 | grep -i 'data format'

# Iterate on a parser with a sample payload via a file input
telegraf --config /tmp/format-test.conf --test

# Confirm the installed version (parsers vary by release)
telegraf --version

# Validate a single input after fixing the format
telegraf --config /etc/telegraf/telegraf.conf --test --input-filter http

# Watch for the error live
journalctl -u telegraf -f | grep -i 'data format'

Conclusion

invalid data format means the data_format value is not a parser Telegraf recognizes — almost always a typo, wrong casing, an old alias, or a parser that needs a companion sub-table you did not supply. Verify the exact name against your installed version, pair it with the required configuration, and test against a sample payload with a file input and telegraf --test. A correct parser name plus its sub-table turns raw JSON, CSV, or Prometheus text into clean metrics.