🚨 Logstash Error: 'Unable to reload pipeline' — Cause, Fix, and Troubleshooting Guide

Overview

With config.reload.automatic: true (or when you send the process a SIGHUP), Logstash periodically re-reads its pipeline configuration and, if the files changed, swaps in a new pipeline without a full restart. The swap is not always possible. When it fails, the old pipeline keeps running and the agent logs the reason it could not reload:

[ERROR][logstash.agent][main] Unable to reload pipeline {:pipeline_id=>"main", :error=>"Cannot reload pipeline, because the existing pipeline is not reloadable", ...}

You will often see the accompanying action-level error naming the reload that failed:

[ERROR][logstash.agent] Failed to execute action {:action=>LogStash::PipelineAction::Reload ...}

There are two failure modes behind this message. The first is a bad new config: the changed file is syntactically invalid, so the reload is rejected and the previous good pipeline continues untouched. The second is a non-reloadable pipeline: at least one plugin in the running pipeline cannot be hot-swapped (stdin is the classic example), which marks the whole pipeline non-reloadable regardless of what you changed.

Symptoms

• Unable to reload pipeline with error=>"...existing pipeline is not reloadable" in logstash-plain.log.
• A companion Failed to execute action {:action=>LogStash::PipelineAction::Reload ...} line.
• You edited a .conf file and the change never takes effect, even though config.reload.automatic is on.
• Auto-reload works for most pipelines but one specific pipeline never picks up changes.
• The monitoring API reports "reloadable" : false for the affected pipeline.

Common Root Causes

• Invalid new configuration — a syntax error (unbalanced braces, unknown setting, bad conditional) in the edited file; the reload is rejected and the old pipeline stays live.
• A non-reloadable plugin in the pipeline — inputs like stdin, and certain other plugins, do not support hot reload, so the pipeline is flagged non-reloadable as a whole.
• A plugin that changes identity on reload — some settings cannot be altered live and require the plugin to be re-instantiated, which reload cannot do safely.
• Reload interval too aggressive — a very short config.reload.interval picks up a file mid-edit (half-written), producing transient parse failures on every save.
• Filesystem/glob picking up partial files — editors writing .swp/temp files into the watched conf.d directory get read as config and fail to parse.

How to diagnose

Never let auto-reload be the first thing that sees your new config. Validate it explicitly with -t (--config.test_and_exit) before it can be picked up:

sudo -u logstash /usr/share/logstash/bin/logstash \
  -f /etc/logstash/conf.d/main.conf \
  --config.test_and_exit --path.settings /etc/logstash
# Configuration OK  <- must see this before deploying

Ask the monitoring API whether the running pipeline even claims to be reloadable. If reloadable is false, no valid config change will hot-swap:

curl -s localhost:9600/_node/pipelines?pretty | grep -A5 '"reloadable"'
# "reloadable" : false  <- a non-reloadable plugin is present

Confirm which reload mode is in effect and how often it fires:

# logstash.yml
config.reload.automatic: true
config.reload.interval: 3s

Watch the log while you touch the config so you catch the exact reason — parse error versus non-reloadable:

sudo tail -f /var/log/logstash/logstash-plain.log | grep -Ei 'reload|PipelineAction'

If the pipeline is non-reloadable, identify the offending plugin. A stdin input, for example, makes the whole pipeline non-reloadable:

input {
  stdin { }          # not reloadable — forces a full restart to change
}

Fixes

Gate every deploy behind -t. The most common cause is a syntax error in the new file; a mandatory validation step removes it entirely. Wire it into your config-management or CI step:

sudo -u logstash /usr/share/logstash/bin/logstash \
  -f /etc/logstash/conf.d/ \
  --config.test_and_exit --path.settings /etc/logstash \
  && sudo systemctl reload logstash

For pipelines that use non-reloadable plugins, deploy with an explicit restart instead of relying on auto-reload. Do not fight the reload system — restart the pipeline (or the service) when you know a hot swap is impossible:

sudo systemctl restart logstash

Keep config.reload.interval sane so the watcher does not read half-written files. A few seconds is plenty; sub-second intervals invite transient parse failures:

# logstash.yml
config.reload.automatic: true
config.reload.interval: 3s

Write config atomically. Render to a temp file and mv it into place so the watcher only ever sees a complete file, and keep editor temp files out of conf.d:

install -m 0644 /tmp/main.conf.new /etc/logstash/conf.d/main.conf

What to watch out for

• The old pipeline keeps running on a failed reload. That is by design and is good — but it means a broken config can pass silently in logs while you believe your change is live. Confirm with the monitoring API.
• reloadable: false is a property of the plugins, not your edit. No amount of config-fixing will make a stdin-bearing pipeline hot-swap; plan a restart.
• Watch the watched directory. Editor swap files, backups, and half-written renders in conf.d are read as config. Edit elsewhere and move the finished file in.
• A too-short interval fights you. If you see intermittent parse errors that “fix themselves,” lengthen config.reload.interval and write atomically.
• systemctl reload vs restart. Reload triggers a hot swap (subject to the same rules); restart tears the pipeline down and back up. Use restart when the pipeline is non-reloadable.

Related

• Logstash ‘PipelineAction::Create’ failed to execute
• Logstash ‘Pipeline aborted due to error’
• Logstash ‘No configuration found’ pipeline error