[Docs] Restore troubleshooting content

docs/reference/toc.yml

@@ -26,6 +26,12 @@ toc:
       - file: reading.md
       - file: searching.md
       - file: aggregations.md
+  - file: troubleshoot/index.md
+    children: 
+      - file: troubleshoot/missing-required-property.md
+      - file: troubleshoot/error-no-such-method.md
+      - file: troubleshoot/apache-errors.md
+      - file: troubleshoot/typed-keys-serialization.md
   - file: javadoc-source-code.md
   - file: external-resources.md
   - file: java-low-level-rest-client.md

docs/reference/troubleshoot/apache-errors.md

@@ -0,0 +1,37 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/io-reactor-errors.html
+---
+
+# Apache errors [io-reactor-errors]
+
+Sending requests can sometimes fail with one of the following errors, coming from the Apache http-client library:
+
+* `Request cannot be executed; I/O reactor status: STOPPED`
+* `I/O reactor terminated abnormally`
+* `I/O reactor has been shut down`
+
+The I/O Reactor is the internal event loop in the http client library. It can terminate when an application callback throws an `Error`, like an `OutOfMemoryError` or a `StackOverflowError`. Remember that `Error` is different from a regular `Exception` and – [quoting the Java documentation](https://docs.oracle.com/javase/8/docs/api/?java/lang/Error.md) – *indicates serious problems that a reasonable application should not try to catch*.
+
+In the context of the Elasticsearch Java clients, this can happen on two occasions:
+
+* the application calls the low level `RestClient` directly, using the asynchronous `performRequestAsync` method, and an `Error` is thrown in the `ResponseListener` provided by the application.
+* an `OutOfMemoryError` happens while buffering the body of an http response.
+
+In the first case, it is the application’s responsibility to catch `Error` in its `ResponseListener` and decide what to do when these errors happen.
+
+The second case is taken care of in the Java API Client since version 8.12: the error is wrapped in a `RuntimeException` that is reported to the application.
+
+In previous versions of the Java API Client, you can copy/paste the `SafeResponseConsumer` class in your project and initialize the `RestClientTransport` as follows:
+
+```java
+RestClient restClient = ...
+JsonpMapper mapper = ...
+RestClientOptions options = new RestClientOptions(
+    SafeResponseConsumer.DEFAULT_REQUEST_OPTIONS
+);
+RestClientTransport transport = new RestClientTransport(
+    restClient, mapper, options
+);
+```
+

docs/reference/troubleshoot/error-no-such-method.md

@@ -0,0 +1,35 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/no-such-method-request-options.html
+---
+
+# Error: No such method [no-such-method-request-options]
+
+In certain contexts you may encounter an error when creating the `ElasticsearchClient` saying that the method `RequestOptions$Builder.removeHeader` does not exist:
+
+```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 [Spring Boot Maven Plugin](https://docs.spring.io/spring-boot/docs/current/maven-plugin/reference/htmlsingle/), as this plugin [defines versions for commonly used libraries](https://github.com/spring-projects/spring-boot/blob/main/spring-boot-project/spring-boot-dependencies/build.gradle), 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](../installation.md)).
+
+Using Gradle:
+
+```groovy
+implementation 'org.elasticsearch.client:elasticsearch-rest-client:9.0.0-beta1'
+```
+
+Using Maven:
+
+```xml
+<dependency>
+    <groupId>org.elasticsearch.client</groupId>
+    <artifactId>elasticsearch-rest-client</artifactId>
+    <version>9.0.0-beta1</version>
+</dependency>
+```
+

docs/reference/troubleshoot/index.md

@@ -0,0 +1,19 @@
+---
+navigation_title: Troubleshoot
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/troubleshooting.html
+---
+
+# Troubleshooting: {{es}} Java client [troubleshooting]
+
+
+## Exceptions [_exceptions] 
+
+* [`MissingRequiredPropertyException` in a response](missing-required-property.md)
+* [`NoSuchMethodError RequestOptions$Builder.removeHeader` when creating a client](error-no-such-method.md)
+* [Apache http-client I/O reactor errors](apache-errors.md)
+
+
+## Miscellaneous [_miscellaneous] 
+
+* [Serializing aggregations and suggestions without typed keys](typed-keys-serialization.md)

docs/reference/troubleshoot/missing-required-property.md

@@ -0,0 +1,44 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/missing-required-property.html
+---
+
+# Missing required property [missing-required-property]
+
+The Java API Client distinguishes optional and required properties. Optional properties are marked with the `@Nullable` annotation.
+
+When an API object is built and a required property hasn’t been set, a `MissingRequiredPropertyException` is thrown. This applies both to request object built by your application and to response objects returned by Elasticsearch, so that you can be assured that a property that does not have the `@Nullable` annotation will never be `null`.
+
+However, there may be bugs in the [Elasticsearch API specification](https://github.com/elastic/elasticsearch-specification) where a response object’s property is incorrectly required, leading to a `MissingRequiredPropertyException` when deserializing a response. If this happens, here’s how you can work around it:
+
+* Make sure you use the latest release of the Java API Client. The issue may already have been fixed.
+* If the issue is still present on the latest version, [open an issue](https://github.com/elastic/elasticsearch-java/issues/new/choose) so that we can fix it in the next release. Please help us to improve the Java API Client.
+* Temporarily disable required property checks for the offending request:
+
+::::{warning} 
+This is a workaround. Do not consider this as a permanent solution, and please [open an issue](https://github.com/elastic/elasticsearch-java/issues/new/choose) so that the problem can be fixed in a future release.
+::::
+
+
+```java
+    ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(true);
+    SomeRequest request = SomeRequest.of(...);
+    SomeResponse response = esClient.someApi(request);
+    ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(false);
+    // Do something with response
+}
+```
+
+The `DANGEROUS_disableRequiredPropertiesCheck` method disables required property checks on the current thread, and for response deserialization in asynchronous requests. As its name implies, it is dangerous as it removes the guarantees of properties that are not `@Nullable`. This is a temporary workaround until the issue is fixed.
+
+Note that the result of this method is an `AutoCloseable` object that resets required property checks to its previous setting. You can therefore use it in a try-with-resource block as follows:
+
+```java
+try (ApiTypeHelper.DisabledChecksHandle h =
+        ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(true)) {
+    SomeRequest request = SomeRequest.of(...);
+    SomeResponse response = esClient.someApi(request);
+    // Do something with response
+}
+```
+

docs/reference/troubleshoot/typed-keys-serialization.md

@@ -0,0 +1,47 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/serialize-without-typed-keys.html
+---
+
+# Typed keys serialization [serialize-without-typed-keys]
+
+{{es}} search requests accept a `typed_key` parameter that allow returning type information along with the name in aggregation and suggestion results (see the [aggregations documentation](docs-content://explore-analyze/query-filter/aggregations.md#return-agg-type) for additional details).
+
+The Java API Client always adds this parameter to search requests, as type information is needed to know the concrete class that should be used to deserialize aggregation and suggestion results.
+
+Symmetrically, the Java API Client also serializes aggregation and suggestion results using this `typed_keys` format, so that it can correctly deserialize the results of its own serialization.
+
+```java
+ElasticsearchClient esClient = ...
+JsonpMapper mapper = esClient._jsonpMapper();
+
+StringWriter writer = new StringWriter();
+try (JsonGenerator generator = mapper.jsonProvider().createGenerator(writer)) {
+    mapper.serialize(searchResponse, generator);
+}
+String result = writer.toString();
+
+// The aggregation property provides the "avg" type and "price" name
+assertTrue(result.contains("\"aggregations\":{\"avg#price\":{\"value\":3.14}}}"));
+```
+
+However, in some use cases serializing objects in the `typed_keys` format may not be desirable, for example when the Java API Client is used in an application that acts as a front-end to other services that expect the default format for aggregations and suggestions.
+
+You can disable `typed_keys` serialization by setting the `JsonpMapperFeatures.SERIALIZE_TYPED_KEYS` attribute to `false` on your mapper object:
+
+```java
+ElasticsearchClient esClient = ...
+// Create a new mapper with the typed_keys feature disabled
+JsonpMapper mapper = esClient._jsonpMapper()
+    .withAttribute(JsonpMapperFeatures.SERIALIZE_TYPED_KEYS, false);
+
+StringWriter writer = new StringWriter();
+try (JsonGenerator generator = mapper.jsonProvider().createGenerator(writer)) {
+    mapper.serialize(searchResponse, generator);
+}
+String result = writer.toString();
+
+// The aggregation only provides the "price" name
+assertTrue(result.contains("\"aggregations\":{\"price\":{\"value\":3.14}}}"));
+```
+