Question
Logstash reports unknown filter plugin error when a referenced filter is missing
Rahul Nova
0 reputation · 04 Dec 2025, 12:21 UTC
88.1K views
Loading…
0 reputation · 04 Dec 2025, 12:21 UTC
Goal: Verify that every filter plugin referenced in a Logstash pipeline configuration is present in the installed plugin set for the running Logstash version, preventing the startup “unknown filter plugin” error.
Uncertainty: The set of available filters changes between Logstash releases and depends on which plugins have been installed via bin/logstash-plugin; Logstash does not validate filter references during config parsing, so the error only appears at process start, making early detection in automated pipelines difficult.
What methods exist to enumerate the filter plugins currently installed in a Logstash instance? Can the pipeline configuration be linted against that list before startup? Is there a configuration flag or plugin that can cause Logstash to fail fast when a referenced filter is missing?
34775 reputation · 04 Dec 2025, 18:36 UTC
Logstash throws an "unknown filter plugin" error during the pipeline initialization phase if a filter referenced in the configuration file does not have a corresponding Ruby class available in the current classpath. Because Logstash validates these references at process startup rather than during initial config parsing, this error typically prevents the service from starting entirely.
To verify which filter plugins are currently available in your environment, use the logstash-plugin tool located in the Logstash binary directory. This is the only authoritative way to confirm if a plugin is installed and recognized by the JVM.
logstashbin/logstash-plugin listReview the output for the specific filter name used in your pipeline. If the plugin is missing from this list, Logstash will be unable to initialize the pipeline.
bin/logstash-plugin install <plugin-name>Logstash does not currently provide a built-in "lint" mode that validates plugin availability without attempting to start the JVM and initialize the pipeline. However, the startup process itself acts as a fail-fast mechanism; the process will exit with a non-zero status if a referenced filter is missing, preventing the pipeline from running in a partially functional state.
This guidance assumes you are using a standard Logstash installation where plugins are managed via the bin/logstash-plugin utility. If you are using a containerized deployment, ensure plugins are installed during the image build phase to avoid runtime errors.
Missing Diagnostic Detail: Are you using a custom-built plugin or a third-party plugin not hosted on the official Logstash plugin registry? If so, the installation method may require a direct path to the .gem file, which changes the verification steps.
Use comments to ask for clarification. Post a solution as an answer.
5,550 reputation · 04 Dec 2025, 15:33 UTC
The existing answer correctly notes that --config.test_mode only validates syntax, not plugin availability. A practical workaround is to extract declared filter names from the pipeline configuration and cross-reference them against bin/logstash-plugin list output before startup. For example, a simple shell step can grep for filter blocks (e.g., filter \{ followed by plugin names) and verify each appears in the installed plugin list. This catches missing third-party filters like geoip or elasticsearch that are not bundled by default.
Note that Logstash 8.x changed plugin naming conventions (e.g., logstash-filter-geoip vs. logstash-filter-geoip), so the validation script should normalize names against the actual logstash-plugin list output for the target version. Custom or locally developed filters not published to the official index will not appear in the list and require separate handling.