From caba4f621daeaa20776c96d280c0ca183b9925e1 Mon Sep 17 00:00:00 2001
From: Sylvain Wallez <sylvain@elastic.co>
Date: Wed, 16 Aug 2023 17:05:16 +0200
Subject: [PATCH] Add docs for Exception caused by rest-client version mismatch
 (#647)

---
 docs/troubleshooting/index.asciidoc           | 10 ++++--
 .../no-such-method-request-options.asciidoc   | 36 +++++++++++++++++++
 2 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 docs/troubleshooting/no-such-method-request-options.asciidoc

diff --git a/docs/troubleshooting/index.asciidoc b/docs/troubleshooting/index.asciidoc
index 25435df68..f011fbf94 100644
--- a/docs/troubleshooting/index.asciidoc
+++ b/docs/troubleshooting/index.asciidoc
@@ -4,11 +4,16 @@
 // * <<debugging>>
 // * <<deprecation-warnings>>
 
-.Exceptions
+[discrete]
+=== Exceptions
 
 * <<missing-required-property>>
-* <<serialize-without-typed-keys>>
+* <<no-such-method-request-options>>
+
+[discrete]
+=== Miscellaneous
 
+* <<serialize-without-typed-keys>>
 
 // [[debugging]]
 // === Debugging
@@ -17,4 +22,5 @@
 // === Elasticsearch deprecation warnings
 
 include::missing-required-property.asciidoc[]
+include::no-such-method-request-options.asciidoc[]
 include::serialize-without-typed-keys.asciidoc[]
diff --git a/docs/troubleshooting/no-such-method-request-options.asciidoc b/docs/troubleshooting/no-such-method-request-options.asciidoc
new file mode 100644
index 000000000..942f79588
--- /dev/null
+++ b/docs/troubleshooting/no-such-method-request-options.asciidoc
@@ -0,0 +1,36 @@
+
+[[no-such-method-request-options]]
+=== `NoSuchMethodError RequestOptions$Builder.removeHeader` when creating a client
+
+In certain contexts you may encounter an error when creating the `ElasticsearchClient` saying that the method `RequestOptions$Builder.removeHeader` does not exist:
+
+["source","java"]
+--------------------------------------------------
+java.lang.NoSuchMethodError: 'org.elasticsearch.client.RequestOptions$Builder org.elasticsearch.client.RequestOptions$Builder.removeHeader(java.lang.String)'
+--------------------------------------------------
+
+This method was introduced in `elasticsearch-rest-client` version 7.16.0. The error happens because your project is using an older version of this dependency.
+
+This happens in particular when the project is using the https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/[Spring Boot Maven Plugin], as this plugin https://github.com/spring-projects/spring-boot/blob/main/spring-boot-project/spring-boot-dependencies/build.gradle[defines versions for commonly used libraries], including `elasticsearch-rest-client`. Depending on the version of Spring Boot used in the project, that version may be outdated.
+
+To solve this issue, you have to add the `elasticsearch-rest-client` dependency explicitly in your project, with the same version as `elasticsearch-java` (see also <<installation>>).
+
+Using Gradle:
+
+["source","groovy",subs="attributes+"]
+--------------------------------------------------
+implementation 'org.elasticsearch.client:elasticsearch-rest-client:{version}'
+--------------------------------------------------
+
+
+Using Maven:
+
+["source","xml",subs="attributes+"]
+--------------------------------------------------
+<dependency>
+    <groupId>org.elasticsearch.client</groupId>
+    <artifactId>elasticsearch-rest-client</artifactId>
+    <version>{version}</version>
+</dependency>
+--------------------------------------------------
+