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.

Steps to test a Logstash pipeline configuration:

Open a terminal on the Logstash host.

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.

Confirm the test exits with status 0 when the configuration is valid.
```
$ echo $?
0
```

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.

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

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.