How to test a Logstash pipeline configuration

Testing a Logstash pipeline configuration before a restart or reload catches syntax problems early, which reduces ingestion downtime and avoids failed service starts during routine edits.

The --config.test_and_exit flag parses the active pipeline configuration and exits without starting inputs or outputs. On Debian and RPM installs, combining it with --path.settings /etc/logstash makes the check use /etc/logstash/logstash.yml, /etc/logstash/pipelines.yml, and the packaged logging settings instead of the archive or Docker defaults.

Current Logstash releases block superuser runs unless allow_superuser is enabled, so package-based tests are safest under the logstash service account with a temporary --path.data directory. The check also does not validate grok pattern correctness or runtime connectivity to remote outputs, so a passing result only proves that the pipeline syntax and settings can be compiled.

1. Open a terminal on the Logstash host.
2. Run the configuration test with the packaged settings directory and a temporary data path.

   $ sudo -u logstash /usr/share/logstash/bin/logstash --path.settings /etc/logstash --path.data /tmp/logstash-configtest --config.test_and_exit
   Using bundled JDK: /usr/share/logstash/jdk
   [2026-04-07T08:03:33,559][INFO ][logstash.runner          ] Starting Logstash {"logstash.version"=>"9.2.3", "jruby.version"=>"jruby 9.4.13.0 (3.1.4) 2025-06-10 9938a3461f OpenJDK 64-Bit Server VM 21.0.9+10-LTS on 21.0.9+10-LTS +indy +jit"}
   Configuration OK
   [2026-04-07T08:03:34,546][INFO ][logstash.runner          ] Using config.test_and_exit mode. Config Validation Result: OK. Exiting Logstash

   The --path.data directory must be writable by the user running the test, and using a throwaway path keeps the check away from the service data directory in /var/lib/logstash.

   Current releases default allow_superuser to false, so running the same command as root fails with Logstash cannot be run as superuser unless that setting is explicitly changed.

3. Confirm the test exits with status 0 when the configuration is valid.

   $ echo $?
   0

4. Re-run the test against a single pipeline file when the error needs to be isolated.

   $ sudo -u logstash /usr/share/logstash/bin/logstash --path.settings /etc/logstash --path.data /tmp/logstash-configtest --config.test_and_exit -f /etc/logstash/conf.d/pipeline.conf
   Using bundled JDK: /usr/share/logstash/jdk
   [2026-04-07T08:04:16,940][WARN ][logstash.config.source.multilocal] Ignoring the 'pipelines.yml' file because command line options are specified
   [2026-04-07T08:04:16,986][FATAL][logstash.runner          ] The given configuration is invalid. Reason: Expected one of [ \t\r\n], "#", "=>" at line 3, column 36 (byte 56) after filter {
     mutate {
       add_field => { "ingest_source"
   [2026-04-07T08:04:16,999][FATAL][org.logstash.Logstash    ] Logstash stopped processing because of an error: (SystemExit) exit

   The -f option ignores /etc/logstash/pipelines.yml for that run and validates only the specified file or directory.

5. Edit the reported pipeline file to fix the first syntax error that Logstash reports.

   $ sudoedit /etc/logstash/conf.d/pipeline.conf

   Related: How to configure Logstash pipelines

6. Re-run the configuration test until it reports Config Validation Result: OK.

   $ sudo -u logstash /usr/share/logstash/bin/logstash --path.settings /etc/logstash --path.data /tmp/logstash-configtest --config.test_and_exit
   Configuration OK
   [2026-04-07T08:03:34,546][INFO ][logstash.runner          ] Using config.test_and_exit mode. Config Validation Result: OK. Exiting Logstash

   --config.test_and_exit does not validate grok pattern correctness or remote output reachability, so follow a clean result with a representative runtime check when those parts changed.

   Related: How to debug Logstash pipelines