How to test a Logstash pipeline configuration

Testing pipeline configuration catches syntax mistakes before they prevent Logstash from starting or reloading, reducing ingestion downtime during changes.

Logstash validates pipeline configs by parsing and compiling the configured pipelines with logstash –config.test_and_exit, then exiting without starting inputs or outputs. Pointing --path.settings to /etc/logstash loads /etc/logstash/logstash.yml and /etc/logstash/pipelines.yml so validation uses the same settings as the packaged service.

Config validation confirms pipeline structure and plugin settings, but it does not prove network connectivity, credentials, or filesystem permissions at runtime. Running the test as root can create root-owned files under /var/lib/logstash on some deployments, causing the logstash service to fail later.

1. Open a terminal on the Logstash host.
2. Run the pipeline configuration test using the service settings directory.

   $ sudo /usr/share/logstash/bin/logstash --path.settings /etc/logstash --config.test_and_exit
   Using bundled JDK: /usr/share/logstash/jdk
   Sending Logstash logs to /var/log/logstash which is now configured via log4j2.properties
   [2026-01-07T04:48:30,726][WARN ][logstash.runner          ] NOTICE: Running Logstash as a superuser is strongly discouraged as it poses a security risk. Set 'allow_superuser' to false for better security.
   [2026-01-07T04:48:30,731][INFO ][logstash.runner          ] Log4j configuration path used is: /etc/logstash/log4j2.properties
   [2026-01-07T04:48:30,732][INFO ][logstash.runner          ] Starting Logstash {"logstash.version"=>"8.19.9", "jruby.version"=>"jruby 9.4.9.0 (3.1.4) 2024-11-04 547c6b150e OpenJDK 64-Bit Server VM 21.0.9+10-LTS on 21.0.9+10-LTS +indy +jit [aarch64-linux]"}
   ##### snipped #####
   Configuration OK
   [2026-01-07T04:48:31,326][INFO ][logstash.runner          ] Using config.test_and_exit mode. Config Validation Result: OK. Exiting Logstash

   Replace sudo with sudo -u logstash when the service runs under the logstash user.

3. Confirm the command exits with status 0 after a successful validation.

   $ echo $?
   0

4. Test a specific pipeline config file to isolate validation errors.

   $ sudo /usr/share/logstash/bin/logstash --path.settings /etc/logstash --config.test_and_exit -f /etc/logstash/conf.d/pipeline.conf
   Using bundled JDK: /usr/share/logstash/jdk
   Sending Logstash logs to /var/log/logstash which is now configured via log4j2.properties
   [2026-01-07T04:48:47,353][WARN ][logstash.runner          ] NOTICE: Running Logstash as a superuser is strongly discouraged as it poses a security risk. Set 'allow_superuser' to false for better security.
   [2026-01-07T04:48:47,356][INFO ][logstash.runner          ] Log4j configuration path used is: /etc/logstash/log4j2.properties
   [2026-01-07T04:48:47,357][INFO ][logstash.runner          ] Starting Logstash {"logstash.version"=>"8.19.9", "jruby.version"=>"jruby 9.4.9.0 (3.1.4) 2024-11-04 547c6b150e OpenJDK 64-Bit Server VM 21.0.9+10-LTS on 21.0.9+10-LTS +indy +jit [aarch64-linux]"}
   ##### snipped #####
   [2026-01-07T04:48:47,508][FATAL][logstash.runner          ] The given configuration is invalid. Reason: Expected one of [ \t\r\n], "#", "=>" at line 3, column 17 (byte 103) after filter { grok { match => { "message" => "%{COMBINEDAPACHELOG" } }
   output { stdout 
   ##### snipped #####

5. Edit the reported pipeline config file to correct the line and column shown in the validation error.

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

   Related: How to configure Logstash pipelines

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

   $ sudo /usr/share/logstash/bin/logstash --path.settings /etc/logstash --config.test_and_exit
   Configuration OK
   [2026-01-07T04:48:31,326][INFO ][logstash.runner          ] Using config.test_and_exit mode. Config Validation Result: OK. Exiting Logstash