🚨 Logstash Error: 'LogStash::ConfigurationError' — Cause, Fix, and Troubleshooting Guide

Overview

Logstash pipeline configs are written in a small domain-specific language. Before a pipeline can start, that DSL is parsed — and if the grammar is violated, the agent refuses to run the pipeline and logs a ConfigurationError that names the exact location of the problem:

[ERROR][logstash.agent][main] Failed to execute action {:id=>:main, :action_type=>LogStash::ConfigurationError, :message=>"Expected one of [ \t\r\n], \"#\", \"{\", \"}\" at line 14, column 3 (byte 210) after filter {\n  grok {\n    match => { \"message\" => \"%{COMBINEDAPACHELOG}\" }\n  ", :backtrace=>...}

The Expected one of ... phrasing means the parser reached a point where it wanted a delimiter, comment, or brace and found something else. The line, column, and byte offset point at where parsing broke — usually just after the real mistake (a brace you forgot to close, a value you forgot to quote). This is a startup-time parse failure: the pipeline never loads, so no events flow until the config is valid.

Symptoms

• LogStash::ConfigurationError in logstash-plain.log with Expected one of [...] at line X, column Y (byte Z).
• The pipeline (or all of Logstash) fails to start; systemctl status logstash shows the service failing or restarting.
• bin/logstash -t reports the same location instead of Configuration OK.
• The named line often looks fine — the actual error (a missing } or =>) is a line or two earlier.
• Recently edited config: a plugin block added, a setting renamed, or a value pasted from documentation.

Common Root Causes

• Unbalanced braces or brackets — a missing or extra {, }, [, or ], so the parser never sees the block close where it expects.
• Missing => — a plugin option written as name value or name: value instead of name => value.
• Unquoted string value — a bare string where the DSL requires quotes (e.g. index => app-logs instead of "app-logs").
• Stray or trailing comma — an extra comma in a hash/array, or one where the grammar does not allow it.
• Unknown or mistyped plugin setting — an option name the plugin does not define, which the parser/validator rejects.
• Wrong value type — a string where a number or boolean is expected (e.g. workers => "four"), rejected during validation.

How to diagnose

Never restart-and-pray. Run the config test, which prints the precise line/column and exits without starting the pipeline:

sudo -u logstash /usr/share/logstash/bin/logstash \
  -t -f /etc/logstash/conf.d/ --path.settings /etc/logstash
# equivalently: --config.test_and_exit

Open the reported file at that line and read upward — the reported column is where the parser gave up, but the missing brace or quote is usually just before it. Here is a config that produces the error above (the grok block is never closed before date begins):

filter {
  grok {
    match => { "message" => "%{COMBINEDAPACHELOG}" }
  # <-- missing } to close grok
  date {
    match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
  }
}

If it is not obvious, bisect: temporarily comment out plugin blocks and re-run -t until it passes, then reintroduce them one at a time. For “unknown setting” or type errors, check the plugin’s option names and types:

# List installed plugins to confirm the plugin name is right
/usr/share/logstash/bin/logstash-plugin list | grep -i grok

Fixes

Balance every block and use the correct operator and quoting. The corrected version of the example simply closes grok before date:

filter {
  grok {
    match => { "message" => "%{COMBINEDAPACHELOG}" }
  }
  date {
    match => ["timestamp", "dd/MMM/yyyy:HH:mm:ss Z"]
  }
}

Use => (not :), quote string values, and give options their correct types. A few common corrections:

output {
  elasticsearch {
    hosts => ["https://es.internal:9200"]   # array of quoted strings
    index => "app-logs-%{+YYYY.MM.dd}"       # quoted string, not bare
    user  => "logstash_writer"               # => not :
  }
}

For pipeline-level type errors (for example in pipelines.yml), give numeric settings numbers, not quoted strings:

# /etc/logstash/pipelines.yml
- pipeline.id: main
  path.config: "/etc/logstash/conf.d/*.conf"
  pipeline.workers: 4          # number, not "four"
  pipeline.batch.size: 250

Re-run the test until it passes, then restart and confirm the pipeline starts:

sudo -u logstash /usr/share/logstash/bin/logstash \
  -t -f /etc/logstash/conf.d/ --path.settings /etc/logstash   # expect: Configuration OK
sudo systemctl restart logstash
sudo tail -f /var/log/logstash/logstash-plain.log | grep -Ei 'ConfigurationError|Pipeline started'

What to watch out for

• The reported line/column is where parsing failed, not always where the mistake is — read upward from it.
• -t catches syntax and setting-name/type errors, but not runtime logic (a grok that never matches, a bad connection string) — a passing test is necessary, not sufficient.
• An editor with bracket matching and DSL syntax highlighting catches most unbalanced-brace errors before you ever deploy.
• Wildcards matter: -f /etc/logstash/conf.d/ concatenates every .conf in that directory, so an error in an unrelated file can break the whole pipeline — test the whole directory, not one file.
• Keep configs in version control and run --config.test_and_exit in CI so a broken edit never reaches a running node.

Related

• No configuration found
• PipelineAction::Create failed
• Pipeline aborted due to error