🚨 Logstash Error: 'logstash.licensechecker' — Cause, Fix, and Troubleshooting Guide

Overview

When you enable X-Pack monitoring or central pipeline management, Logstash contacts an Elasticsearch cluster to read the license and to ship its own monitoring data. That check runs through the license reader, and when it cannot reach the cluster or authenticate to it, the license checker logs an error and the monitoring subsystem does not start. In /var/log/logstash/logstash-plain.log it appears as:

[ERROR][logstash.licensechecker.licensereader][main] Unable to retrieve license information from license server {:message=>"Got response code '401' contacting Elasticsearch at URL 'https://es.internal:9200/_xpack'"}

The key detail is usually the HTTP status embedded in the message. A 401 means the request reached Elasticsearch but the credentials were rejected. Other variants point at an expired license or a monitoring cluster that is simply the wrong endpoint. Note that this is about the monitoring/management connection configured by xpack.monitoring.* and xpack.management.* — it is separate from your data-output elasticsearch {} blocks, which may be perfectly healthy while this fails.

Symptoms

• [logstash.licensechecker.licensereader] Unable to retrieve license information from license server at startup.
• A Got response code '401' (auth) — or 403, 503, or a connection error — in the message.
• Monitoring data never appears in the Stack Monitoring UI, or central management cannot load pipelines.
• The data path still works: your pipelines ingest and output normally while only monitoring is broken.
• Logs mention /_xpack or /_license as the URL being contacted.

Common Root Causes

• Wrong or unset monitoring credentials — with ES security enabled, xpack.monitoring.elasticsearch.username/password are missing or incorrect, producing a 401.
• Expired license — a basic or trial license lapsed, so the cluster reports no valid license for the monitoring features.
• Wrong monitoring cluster — xpack.monitoring.elasticsearch.hosts points at a cluster that does not host the license, or at a data-only endpoint.
• Insufficient role on the monitoring user — the account exists but lacks the logstash_system role’s privileges to read the license.
• TLS not trusted — the monitoring host uses HTTPS with a CA the Logstash JVM does not trust, so the request never completes (surfaces as a handshake failure rather than 401).
• Monitoring collected elsewhere — you moved to Metricbeat/Elastic Agent collection but left xpack.monitoring.enabled: true, so Logstash still tries (and fails) to self-report.

How to diagnose

First separate authentication from reachability. Hit the same license endpoint the checker uses, with the same credentials, from the Logstash host:

# 401 here means the credentials, not the network, are the problem
curl -s -o /dev/null -w '%{http_code}\n' \
  -u logstash_system:$MON_PW https://es.internal:9200/_license

# Read the actual license status
curl -s -u logstash_system:$MON_PW https://es.internal:9200/_license?pretty

Confirm the built-in monitoring user exists and has the expected role:

curl -s -u elastic:$ELASTIC_PW \
  https://es.internal:9200/_security/user/logstash_system?pretty

Check what Logstash is actually configured to use. The relevant settings live in logstash.yml:

# logstash.yml (as-found — inspect these)
xpack.monitoring.enabled: true
xpack.monitoring.elasticsearch.hosts: ["https://es.internal:9200"]
xpack.monitoring.elasticsearch.username: logstash_system

Verify the password env var is present for the service, since an unset ${MON_PW} yields an empty password and a clean 401:

sudo -u logstash bash -c '[ -n "$MON_PW" ] && echo set || echo MISSING'

Fixes

Set valid monitoring credentials using the built-in logstash_system user, whose role is designed exactly for this. Put these in logstash.yml and supply the password from an environment variable or the keystore:

# logstash.yml
xpack.monitoring.enabled: true
xpack.monitoring.elasticsearch.hosts: ["https://es.internal:9200"]
xpack.monitoring.elasticsearch.username: logstash_system
xpack.monitoring.elasticsearch.password: ${MON_PW}
xpack.monitoring.elasticsearch.ssl.certificate_authority: /etc/logstash/certs/ca.crt

Set (or reset) the built-in user’s password on the cluster, then wire it into the Logstash keystore so it is never committed:

# On an ES node: set the logstash_system password
bin/elasticsearch-reset-password -u logstash_system

# On the Logstash host: store it in the keystore as MON_PW
echo "$THE_PASSWORD" | sudo -u logstash \
  /usr/share/logstash/bin/logstash-keystore add MON_PW --stdin

Verify the license and the user after configuring, so you confirm both halves are healthy:

curl -s -u logstash_system:$MON_PW https://es.internal:9200/_license?pretty
curl -s -u logstash_system:$MON_PW https://es.internal:9200/_security/user/logstash_system?pretty

If you collect monitoring via Metricbeat or Elastic Agent instead of Logstash’s internal collector, turn the internal collector off so the license checker stops running at all:

# logstash.yml — external monitoring collection
xpack.monitoring.enabled: false

What to watch out for

• Read the status code. 401 is credentials, 403 is a role/privilege gap, 503 is the cluster being unavailable, and a handshake error is TLS — each needs a different fix.
• logstash_system cannot write data, by design. Do not reuse a data-writing user for monitoring or a data user for monitoring; keep the roles separate.
• HTTPS needs a trusted CA. If the monitoring cluster is on TLS, set ssl.certificate_authority, or the check fails before it ever reaches auth.
• Don’t leave the internal collector on after moving to Metricbeat/Agent. Duplicate collection wastes cycles and keeps this error in your logs; set xpack.monitoring.enabled: false.
• The data path is independent. A failing license check does not stop ingest — but it also means you are flying blind on monitoring, so treat it as urgent, not cosmetic.

Related

• Logstash ‘Elasticsearch Unreachable’ output error
• Logstash Elasticsearch output HTTP 429 rejections
• Logstash SSLHandshakeException PKIX path building failed