🚨 Telegraf Error Guide: 'Undefined but requested input: <name>' — Fix Unknown Input Plugin

Overview

When Telegraf reads a [[inputs.something]] block whose plugin name it does not recognize, it aborts at startup rather than silently skipping the block. The message names the plugin it could not find:

E! [telegraf] Error running agent: Error parsing /etc/telegraf/telegraf.conf, Undefined but requested input: net_response_check

Older and alternate builds phrase the same condition as an “unknown input plugin”:

2026-07-10T12:00:00Z E! error loading config file /etc/telegraf/telegraf.conf: unknown input plugin "prometheus_scraper"

Either way the agent exits non-zero and collects nothing until the name resolves to a real plugin compiled into your binary.

Symptoms

• Telegraf fails to start and systemctl status telegraf shows a restart loop.
• The log names a specific plugin after Undefined but requested input: or unknown input plugin.
• The config looks structurally fine — correct [[inputs.x]] double brackets — but x is not a valid plugin.
• The same config worked on another host running a different Telegraf version.
• Custom or execd-based plugins are referenced by the wrong table name.

Common Root Causes

• Misspelled plugin name — net_response_check instead of net_response, mem_stats instead of mem, or a plural where the plugin is singular.
• Version mismatch — the plugin exists in a newer Telegraf release than the one installed on the host (or was removed/renamed).
• A custom or external plugin referenced as a built-in — an execd external plugin must be configured under [[inputs.execd]], not under its own project name.
• Wrong plugin category — configuring an output or processor name under [[inputs.*]] (e.g. [[inputs.file]] is valid, but [[inputs.influxdb_v2]] is not — that is an output).
• Copy-paste from a blog or AI snippet that invented a plugin that never existed.
• Case or separator errors — Telegraf plugin names are lowercase with underscores; [[inputs.Net_Response]] will not match.

Diagnostic Workflow

List exactly which input plugins your installed binary supports and grep for the one you want. This is the single most useful check — it reflects your version, not the docs:

telegraf plugins inputs | sort | grep -i net
telegraf plugins inputs | wc -l    # total inputs available in this build

Confirm the version so you can cross-check the plugin’s availability in the release notes:

telegraf --version

Test just the block in question to confirm the fix before restarting the service:

telegraf --config /etc/telegraf/telegraf.conf --test --input-filter net_response

The --input-filter flag also proves the canonical name — if the filtered run produces metrics, the name is valid. A correct net_response block looks like this:

[[inputs.net_response]]
  protocol = "tcp"
  address = "localhost:8080"
  timeout = "5s"

If you truly need an external plugin, wire it through execd rather than its own header:

[[inputs.execd]]
  command = ["/usr/local/bin/my-custom-plugin", "--config", "/etc/my-plugin.conf"]
  signal = "none"
  data_format = "influx"

Example Root Cause Analysis

An engineer copied a monitoring snippet that used [[inputs.disk_usage]]. Telegraf refused to start with Undefined but requested input: disk_usage. Running telegraf plugins inputs | grep -i disk returned two real plugins: disk and diskio. There is no disk_usage plugin — the snippet’s author had invented a plausible-sounding name.

The fix was to use the actual disk input, which reports usage per mount point:

[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs", "overlay"]

After the edit, telegraf --test --input-filter disk emitted disk metrics with used_percent fields and the service started normally. The broader lesson: never trust a plugin name from a snippet without confirming it against telegraf plugins inputs on the target version. Plugin names are an exact, versioned contract.

Prevention Best Practices

• Verify every new plugin name against telegraf plugins inputs on the actual host version before deploying.
• Pin the Telegraf version across your fleet so a config that works on one host works on all of them.
• Run telegraf --test in CI; an unknown plugin fails the parse and blocks the deploy.
• Keep external/custom plugins under [[inputs.execd]] and document their commands, not fictitious built-in names.
• When upgrading Telegraf, read the changelog for renamed or removed plugins and update configs in the same change.
• Prefer copying config from telegraf config output over web snippets, since that reflects your installed plugin set.

Quick Command Reference

# List all input plugins compiled into THIS binary
telegraf plugins inputs

# Search for a plugin by keyword
telegraf plugins inputs | grep -i <keyword>

# Confirm version to cross-check plugin availability
telegraf --version

# Validate a single plugin's config and prove the canonical name
telegraf --config /etc/telegraf/telegraf.conf --test --input-filter <plugin>

# Watch startup for the "Undefined but requested input" line
journalctl -u telegraf -f

Conclusion

Undefined but requested input / unknown input plugin means the plugin name in your [[inputs.*]] header does not exist in the Telegraf binary you are running. Confirm the real name with telegraf plugins inputs, check for version drift with telegraf --version, and route custom collectors through execd. A quick telegraf --test in CI catches every one of these before it ever reaches a production restart.