🚨 Telegraf Error Guide: 'error loading config file ... invalid configuration' — Fix TOML and Plugin Config

Overview

Telegraf validates its entire configuration before it starts collecting a single metric. When the parser rejects the file, the agent refuses to boot and systemd logs the failure. The error names the file that failed to parse:

E! error loading config file /etc/telegraf/telegraf.conf: invalid configuration: line 42: invalid TOML syntax

You will also see closely related variants for the same root problem — a config file that does not parse as valid TOML or that contains a key Telegraf does not recognize:

E! [telegraf] Error running agent: error loading config file /etc/telegraf/telegraf.d/inputs.conf: toml: line 12: expected '.' or '=', but got 'input' instead

Because this is a fatal startup error, systemctl start telegraf fails immediately and no metrics flow.

Symptoms

• telegraf exits non-zero at startup and systemctl status telegraf shows activating (auto-restart) or failed.
• journalctl -u telegraf repeats the same invalid configuration line every restart.
• The error references a specific file and, usually, a line number under /etc/telegraf/telegraf.conf or /etc/telegraf/telegraf.d/.
• Removing a recently edited drop-in file lets the agent start, confirming the fault is in that file.
• No data appears in your output (InfluxDB, Prometheus) because the agent never began collecting.

Common Root Causes

• Broken TOML syntax — a missing =, an unclosed string, a stray tab, or a value that is not quoted where TOML requires quoting.
• Malformed table headers — [inputs.cpu] written as [input.cpu], [[inputs.cpu]] written with single brackets, or a missing double bracket for a plugin instance.
• Duplicate keys in the same table — the same option set twice inside one [[inputs.x]] block.
• Unknown configuration option — an option that does not exist for that plugin (often a typo like interval misspelled, or an option copied from a different plugin version).
• Environment variables not expanded — ${TOKEN} referenced but the variable is empty, producing an invalid value at parse time.
• A stray file in telegraf.d/ — a .conf.bak, editor swap file, or non-TOML note that Telegraf still tries to parse because it globs the whole directory.

Diagnostic Workflow

First, ask Telegraf to parse and validate the config without sending any data. --test loads the full configuration, runs one collection cycle, and prints metrics to stdout, so a parse error surfaces here immediately:

telegraf --config /etc/telegraf/telegraf.conf \
         --config-directory /etc/telegraf/telegraf.d --test

If you use a config directory, the offending drop-in may not be the main file. Bisect by testing files individually:

for f in /etc/telegraf/telegraf.d/*.conf; do
  echo "== $f =="
  telegraf --config "$f" --test 2>&1 | grep -i 'invalid\|error' && echo "FAILED: $f"
done

Validate the TOML independently of Telegraf to isolate pure syntax problems from unknown-option problems:

# Any TOML linter works; toml-cli is convenient
toml get /etc/telegraf/telegraf.conf . >/dev/null

A minimal, known-good config block looks like this — compare your file’s structure against it:

[agent]
  interval = "10s"
  flush_interval = "10s"

# Plugin instances use DOUBLE brackets
[[inputs.cpu]]
  percpu = true
  totalcpu = true

[[outputs.influxdb_v2]]
  urls = ["http://localhost:8086"]
  token = "${INFLUX_TOKEN}"
  organization = "acme"
  bucket = "telegraf"

Confirm environment variables referenced in the file are actually populated for the service:

systemctl show telegraf -p EnvironmentFiles
cat /etc/default/telegraf   # or the EnvironmentFile path shown above

Example Root Cause Analysis

A team added a new drop-in /etc/telegraf/telegraf.d/snmp.conf and Telegraf began crash-looping with invalid configuration: line 3. Running telegraf --config /etc/telegraf/telegraf.d/snmp.conf --test reproduced the failure instantly. Line 3 read:

[inputs.snmp]           # WRONG: single brackets
  agents = ["udp://10.0.0.1:161"]

Telegraf treats [inputs.snmp] as a single sub-table of inputs, not as a plugin instance, so the following keys had nowhere valid to live and the parser rejected the file. Changing the header to the double-bracket array-of-tables form Telegraf requires for every plugin instance fixed it:

[[inputs.snmp]]         # CORRECT
  agents = ["udp://10.0.0.1:161"]

After the edit, telegraf --test printed SNMP metrics and systemctl restart telegraf came up cleanly. The lesson: every input, output, processor, and aggregator instance uses [[...]] (array of tables); single brackets are only for the singleton [agent] and [global_tags] sections.

Prevention Best Practices

• Always run telegraf --config ... --test in CI or a pre-deploy hook before restarting the service; treat a non-zero exit as a failed deploy.
• Keep one plugin per drop-in file in telegraf.d/ so a bad edit is isolated and easy to bisect.
• Restrict the config directory to *.conf and never leave .bak, .swp, or editor temp files there — Telegraf parses everything it globs.
• Template configs with a tool that validates TOML (Ansible template + a lint step, or telegraf config as a reference) rather than hand-editing on the host.
• Quote all string values and use double brackets for plugin instances; keep a known-good reference block handy for comparison.
• Verify every ${VAR} reference has a value in the service’s EnvironmentFile before rollout.

Quick Command Reference

# Validate the full configuration without sending data
telegraf --config /etc/telegraf/telegraf.conf \
         --config-directory /etc/telegraf/telegraf.d --test

# Test a single drop-in file to isolate the culprit
telegraf --config /etc/telegraf/telegraf.d/snmp.conf --test

# Print Telegraf's default reference config to compare structure
telegraf config > /tmp/reference.conf

# Watch startup errors live
journalctl -u telegraf -f

# Check which env files the service loads
systemctl show telegraf -p EnvironmentFiles

Conclusion

error loading config file ... invalid configuration is a strict, fail-fast parse error: Telegraf will not start until the file is valid TOML with recognized options. Reproduce it with --test, bisect drop-in files to find the offender, and check the usual suspects — single vs. double brackets, unquoted strings, duplicate keys, and empty environment variables. Wire telegraf --test into your deploy pipeline and the agent will never crash-loop on a bad edit again.