[BUG] MissingRequiredPropertyException: Missing required property 'ForcemergeResponse.shards'

[lonvia]

What is the bug?

When executing a forcemerge() without waiting for completion, OpenSearch 3.8 doesn't return the shard statistics in the response. It returns the task number for the task. This leads to a MissingRequiredPropertyException in the java client because the shards property is required.

How can one reproduce the bug?

client.indices().forcemerge(m -> m.waitForCompletion(false));

reliably produces the exception:

[2026-09-08T09:02:50,496][WARN ][stderr                   ] Exception in thread "main" java.lang.RuntimeException: Missing required property 'ForcemergeResponse.shards'
[2026-09-08T09:02:50,496][WARN ][stderr                   ]     at org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport.extractAndWrapCause(ApacheHttpClient5Transport.java:1162)
[2026-09-08T09:02:50,496][WARN ][stderr                   ]     at org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport.performRequest(ApacheHttpClient5Transport.java:159)
[2026-09-08T09:02:50,496][WARN ][stderr                   ]     at org.opensearch.client.opensearch.indices.OpenSearchIndicesClientBase.forcemerge(OpenSearchIndicesClientBase.java:442)
[2026-09-08T09:02:50,496][WARN ][stderr                   ]     at org.opensearch.client.opensearch.indices.OpenSearchIndicesClientBase.forcemerge(OpenSearchIndicesClientBase.java:452)
[2026-09-08T09:02:50,496][WARN ][stderr                   ]     at de.komoot.photon.App.startNominatimImport(App.java:198)
[2026-09-08T09:02:50,496][WARN ][stderr                   ]     at de.komoot.photon.App.runPhoton(App.java:93)
[2026-09-08T09:02:50,497][WARN ][stderr                   ]     at de.komoot.photon.App.main(App.java:54)
[2026-09-08T09:02:50,497][WARN ][stderr                   ] Caused by: org.opensearch.client.util.MissingRequiredPropertyException: Missing required property 'ForcemergeResponse.shards'
[2026-09-08T09:02:50,497][WARN ][stderr                   ]     at org.opensearch.client.util.ApiTypeHelper.requireNonNull(ApiTypeHelper.java:90)
[2026-09-08T09:02:50,497][WARN ][stderr                   ]     at org.opensearch.client.opensearch._types.ShardsOperationResponseBase.<init>(ShardsOperationResponseBase.java:64)
[2026-09-08T09:02:50,497][WARN ][stderr                   ]     at org.opensearch.client.opensearch.indices.ForcemergeResponse.<init>(ForcemergeResponse.java:69)
[2026-09-08T09:02:50,497][WARN ][stderr                   ]     at org.opensearch.client.opensearch.indices.ForcemergeResponse.<init>(ForcemergeResponse.java:59)
[2026-09-08T09:02:50,497][WARN ][stderr                   ]     at org.opensearch.client.opensearch.indices.ForcemergeResponse$Builder.build(ForcemergeResponse.java:166)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at org.opensearch.client.opensearch.indices.ForcemergeResponse$Builder.build(ForcemergeResponse.java:113)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at org.opensearch.client.json.ObjectBuilderDeserializer.deserialize(ObjectBuilderDeserializer.java:92)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at org.opensearch.client.json.DelegatingDeserializer$SameType.deserialize(DelegatingDeserializer.java:55)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport.decodeResponse(ApacheHttpClient5Transport.java:671)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport.prepareResponse(ApacheHttpClient5Transport.java:556)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport.lambda$performRequestAsync$0(ApacheHttpClient5Transport.java:192)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at java.base/java.util.concurrent.CompletableFuture$UniApply.tryFire(CompletableFuture.java:646)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at java.base/java.util.concurrent.CompletableFuture.postComplete(CompletableFuture.java:510)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at java.base/java.util.concurrent.CompletableFuture.complete(CompletableFuture.java:2179)
[2026-09-08T09:02:50,498][WARN ][stderr                   ]     at org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport$1.completed(ApacheHttpClient5Transport.java:237)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.opensearch.client.transport.httpclient5.ApacheHttpClient5Transport$1.completed(ApacheHttpClient5Transport.java:226)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.core5.concurrent.BasicFuture.completed(BasicFuture.java:148)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.core5.concurrent.ComplexFuture.completed(ComplexFuture.java:72)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.client5.http.impl.async.InternalAbstractHttpAsyncClient$2$1.completed(InternalAbstractHttpAsyncClient.java:321)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.core5.http.nio.support.AbstractAsyncResponseConsumer$1.completed(AbstractAsyncResponseConsumer.java:101)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.core5.http.nio.entity.AbstractBinAsyncEntityConsumer.completed(AbstractBinAsyncEntityConsumer.java:87)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.core5.http.nio.entity.AbstractBinDataConsumer.streamEnd(AbstractBinDataConsumer.java:83)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.core5.http.nio.support.AbstractAsyncResponseConsumer.streamEnd(AbstractAsyncResponseConsumer.java:142)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.client5.http.async.methods.InflatingGzipDataConsumer.streamEnd(InflatingGzipDataConsumer.java:149)
[2026-09-08T09:02:50,499][WARN ][stderr                   ]     at org.apache.hc.client5.http.impl.async.HttpAsyncMainClientExec$1.streamEnd(HttpAsyncMainClientExec.java:283)
[2026-09-08T09:02:50,500][WARN ][stderr                   ]     at org.apache.hc.core5.http.impl.nio.ClientHttp1StreamHandler.dataEnd(ClientHttp1StreamHandler.java:285)
[2026-09-08T09:02:50,500][WARN ][stderr                   ]     at org.apache.hc.core5.http.impl.nio.ClientHttp1StreamDuplexer.dataEnd(ClientHttp1StreamDuplexer.java:376)
[2026-09-08T09:02:50,500][WARN ][stderr                   ]     at org.apache.hc.core5.http.impl.nio.AbstractHttp1StreamDuplexer.onInput(AbstractHttp1StreamDuplexer.java:343)
[2026-09-08T09:02:50,500][WARN ][stderr                   ]     at org.apache.hc.core5.http.impl.nio.AbstractHttp1IOEventHandler.inputReady(AbstractHttp1IOEventHandler.java:64)
[2026-09-08T09:02:50,500][WARN ][stderr                   ]     at org.apache.hc.core5.http.impl.nio.ClientHttp1IOEventHandler.inputReady(ClientHttp1IOEventHandler.java:41)
[2026-09-08T09:02:50,500][WARN ][stderr                   ]     at org.apache.hc.core5.reactor.InternalDataChannel.onIOEvent(InternalDataChannel.java:139)
[2026-09-08T09:02:50,501][WARN ][stderr                   ]     at org.apache.hc.core5.reactor.InternalChannel.handleIOEvent(InternalChannel.java:51)
[2026-09-08T09:02:50,501][WARN ][stderr                   ]     at org.apache.hc.core5.reactor.SingleCoreIOReactor.processEvents(SingleCoreIOReactor.java:193)
[2026-09-08T09:02:50,501][WARN ][stderr                   ]     at org.apache.hc.core5.reactor.SingleCoreIOReactor.doExecute(SingleCoreIOReactor.java:140)
[2026-09-08T09:02:50,501][WARN ][stderr                   ]     at org.apache.hc.core5.reactor.AbstractSingleCoreIOReactor.execute(AbstractSingleCoreIOReactor.java:92)
[2026-09-08T09:02:50,501][WARN ][stderr                   ]     at org.apache.hc.core5.reactor.IOReactorWorker.run(IOReactorWorker.java:44)
[2026-09-08T09:02:50,501][WARN ][stderr                   ]     at java.base/java.lang.Thread.run(Thread.java:1583)

What is the expected behavior?

forcemerge() without waiting for completion should return without throwing an exception. The ForcemergeResponse object should only contain the task number.

What is your host/environment?

Debian Linux, OoenJDK 21, OpenSearch server 3.8.0, opensearch-java 3.10.0

Do you have any additional context?

Running forcemerge in blocking mode returns shard info:

me@machine:$ curl -XPOST "http://localhost:9201/photon/_forcemerge" -H 'Content-Type: application/json' | jq
{
  "_shards": {
    "total": 10,
    "successful": 5,
    "failed": 0
  }
}

Without waiting for completion the response looks like this:

me@machine:$ curl -XPOST "http://localhost:9201/photon/_forcemerge?wait_for_completion=false" -H 'Content-Type: application/json' | jq
{
  "task": "a6ZLm4eQSTufQc-oxnO4uA:66"
}

[xujiantop-crypto]

I'd like to work on this. I can reproduce the deserialization failure and plan to update the Force Merge response schema to model the synchronous _shards and asynchronous task responses as alternatives, with regression tests for both payloads.