Skip to content

doc: Add troubleshooting guide #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 16, 2025
Merged

doc: Add troubleshooting guide #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/modules/opensearch/pages/troubleshooting/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
= Troubleshooting

== Errors and warnings in the OpenSearch logs

=== SSLHandshakeException: Insufficient buffer remaining for AEAD cipher fragment (2). Needs to be more than tag size (16)

The Stackable image of OpenSearch 3.1 uses OpenJDK 21 which is the latest supported JDK version in OpenSearch 3.1.
When using TLSv1.3, which is the default, the following warning can appear in the OpenSearch logs:

----
[WARN ][o.o.h.AbstractHttpServerTransport] [opensearch-nodes-default-0] caught exception while handling client http traffic, closing connection Netty4HttpChannel{localAddress=/...:9200, remoteAddress=/...}
io.netty.handler.codec.DecoderException: javax.net.ssl.SSLHandshakeException: Insufficient buffer remaining for AEAD cipher fragment (2). Needs to be more than tag size (16)
----

This means that a TLS connection could not be established.
Unfortunately, the message does not contain the reason.
The issue with this message is fixed in JDK 24, see https://bugs.openjdk.org/browse/JDK-8331682[JDK-8331682{external-link-icon}^].
OpenSearch 3.2, which supports JDK 24, will therefore show a proper message.

To find out the reason in OpenSearch 3.1, you could temporarily use TLSv1.2 which is not affected by this JDK bug:

[source,yaml]
----
nodes:
configOverrides:
opensearch.yml:
plugins.security.ssl.http.enabled_protocols: TLSv1.2
----

Instead of the warning above, an error message is shown, e.g.:

----
[ERROR][o.o.h.n.s.SecureNetty4HttpServerTransport] [opensearch-nodes-default-0] Exception during establishing a SSL connection: javax.net.ssl.SSLHandshakeException: Received fatal alert: unknown_ca
javax.net.ssl.SSLHandshakeException: Received fatal alert: unknown_ca
----

In this case, the OpenSearch client cannot verify the certificate chain because it does not have the CA certificate which is used to sign the OpenSearch node certificate.
See xref:home:secret-operator:usage.adoc[Usage of the Secret Operator], how to provide the CA certificate to the OpenSearch client and to solve this problem.
1 change: 1 addition & 0 deletions docs/modules/opensearch/partials/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
*** xref:opensearch:usage-guide/operations/pod-placement.adoc[]
*** xref:opensearch:usage-guide/operations/pod-disruptions.adoc[]
*** xref:opensearch:usage-guide/operations/graceful-shutdown.adoc[]
* xref:opensearch:troubleshooting/index.adoc[]
* xref:opensearch:reference/index.adoc[]
** xref:opensearch:reference/crds.adoc[]
*** {crd-docs}/opensearch.stackable.tech/opensearchcluster/v1alpha1/[OpenSearchCluster {external-link-icon}^]
Expand Down
Loading