A top-k DisjunctionMaxQuery search turns a clause's getMaxScore IOException into a RuntimeException

For a top-k search (ScoreMode.TOP_SCORES), DisjunctionMaxScorer and LogOddsFusionScorer build a DisjunctionScoreBlockBoundaryPropagator, whose constructor sorts the clause scorers by getMaxScore(NO_MORE_DOCS). The sort key is a lambda, so it catches the IOException that getMaxScore may throw and rethrows it as new RuntimeException(e) (DisjunctionScoreBlockBoundaryPropagator.java:40 on main). The constructor itself declares IOException and, four lines after the sort, makes the identical call without wrapping, so the type the caller sees depends only on whether the failure happens during the sort or right after it. IndexSearcher.search then throws an unchecked RuntimeException with the IOException as its cause, and code that catches IOException misses it. No Lucene scorer does I/O in getMaxScore(NO_MORE_DOCS), so only custom extension code reaches it (a custom scorer, value source or postings format); a top-level DisjunctionMaxQuery with tie-breaker 0 is spared, one nested among several scoring clauses of a BooleanQuery is not; no result is wrong. The wrap came with LUCENE-8922 (8.3.0); 8.2.0 surfaced the IOException. The fix reads the max scores before the sort.

• getMaxScore(upTo): a Scorer method that returns an upper bound of the scores it can produce up to doc upTo; it declares IOException (Scorer.java:79). Top-k search uses these bounds to skip documents and clauses that cannot make the top k.
• DisjunctionScoreBlockBoundaryPropagator: a helper that DisjunctionMaxScorer (DisjunctionMaxScorer.java:52-53) and LogOddsFusionScorer (LogOddsFusionScorer.java:103-104) build only in TOP_SCORES mode. It sorts the clauses by getMaxScore(NO_MORE_DOCS) so it can stop looking at clauses whose best score is below the current threshold.

// DisjunctionScoreBlockBoundaryPropagator.java:34-43
private static final Comparator<Scorer> MAX_SCORE_COMPARATOR =
    Comparator.comparing(
            (Scorer s) -> {
              try {
                return s.getMaxScore(DocIdSetIterator.NO_MORE_DOCS);
              } catch (IOException e) {
                throw new RuntimeException(e);          // :40
              }
            })
        .thenComparingLong(s -> s.iterator().cost());

// :49-60, the constructor declares IOException
for (Scorer scorer : this.scorers) scorer.advanceShallow(0);          // :52  IOException passes
Arrays.sort(this.scorers, MAX_SCORE_COMPARATOR);                       // :54  becomes RuntimeException
maxScores[i] = this.scorers[i].getMaxScore(DocIdSetIterator.NO_MORE_DOCS); // :58  passes (loop)

1. IndexSearcher.search(q, 10) asks DisjunctionMaxQuery's scorer supplier for a scorer (DisjunctionMaxQuery.java:158); in TOP_SCORES mode DisjunctionMaxScorer builds the propagator (DisjunctionMaxScorer.java:53).
2. The propagator's Arrays.sort (:54) calls the comparator, which calls the custom clause's getMaxScore; it throws IOException("getMaxScore failed"), and the lambda rethrows it as RuntimeException (:40).
3. The RuntimeException travels up through IndexSearcher.search unchanged; the IOException is its cause.

Controls from the hunt's probe and the fact check's probe (main, assertions off): a scorer that fails only on its 2nd getMaxScore call gets java.io.IOException at :58; one that fails in advanceShallow gets IOException at :52; a COMPLETE (non-pruning) search builds no propagator and returns 1 hit; LogOddsFusionQuery gets the same RuntimeException at :40.

Which DisjunctionMaxQuery searches build it. ScorerSupplier.get builds DisjunctionMaxScorer for any tie-breaker (DisjunctionMaxQuery.java:153-159). Only bulkScorer() avoids it: with tie-breaker 0 in TOP_SCORES mode it returns a DisjunctionMaxBulkScorer (:162-170), so a top-level tie-breaker-0 query never builds the propagator. A BooleanQuery gives its scoring clauses its own score mode (BooleanWeight.java:57-59) and calls their get() (BooleanScorerSupplier.java:426, :540). Executed on main and 10.6.0: BooleanQuery(SHOULD dmq(tie 0), SHOULD MatchAllDocsQuery) and BooleanQuery(MUST dmq(tie 0), MUST MatchAllDocsQuery), top-10, throw the same RuntimeException from :40; the same dmq(tie 0) at top level returns 1 hit, and so does BooleanQuery(MUST dmq(tie 0), FILTER MatchAllDocsQuery), which rewrites to that top-level query (BooleanQuery.java:388-392, :279-288).

• Who is hit. Code whose own extension does I/O in a clause's getMaxScore(NO_MORE_DOCS) (for example a custom scorer that bounds scores from doc values) and an error handler that catches IOException to fail a segment or shard cleanly: the failure arrives as an unchecked RuntimeException and bypasses that handler.
• Reach. A DisjunctionMaxQuery with tie-breaker > 0, or with any tie-breaker as one of several scoring clauses of a BooleanQuery (executed); a top-level one with tie-breaker 0 uses DisjunctionMaxBulkScorer and is spared. LogOddsFusionQuery (10.5.0+) is hit too.
• Which extension code. A custom Query/Scorer (the repro). By the same throws IOException signatures, also a custom DoubleValuesSource under FunctionScoreQuery, whose scorer's getMaxScore calls DoubleValues.getMaxScore (FunctionScoreQuery.java:262-264 in lucene/queries; DoubleValues.java:59), or a postings format whose ImpactsSource.getImpacts reads lazily (TermScorer.java:122-123, MaxScoreCache.java:96-109, index/ImpactsSource.java:49). Only the first was run.
• Default vs opt-in. Default searcher, codec and directory; DisjunctionMaxQuery is a stock query, LogOddsFusionQuery exists from 10.5.0. The trigger is the custom code, a legal public extension point (getMaxScore declares IOException). No scale is needed: 1 document, 2 clauses.
• Stock Lucene never reaches it. The in-tree impacts sources answer getMaxScore(NO_MORE_DOCS) from impacts that advanceShallow already decoded; composite scorers only delegate; other leaf scorers return constants.
• Loud, contained. The search fails either way; only the outer exception type is wrong. No wrong or partial results.
• Likelihood: contrived. No public report of it was found since 8.3.0 (2019).

The custom query implements ScorerSupplier directly; its Weight extends ConstantScoreWeight, which is tagged @lucene.internal (ConstantScoreWeight.java:22-29), as is usual for a test in lucene/core. A variant that uses only public API (a plain Weight subclass with its own ScorerSupplier, the cross-model reviewer's own test) fails the same way on 5adff78bb168, assertions on and off. The custom query's scorer iterates all documents with a constant score and throws IOException("getMaxScore failed") from getMaxScore. The test draws no random values. It belongs in lucene/core/src/test/org/apache/lucene/search/, next to TestDisjunctionMaxQuery, and passes :lucene:core:check -x test.

Regression test: this same test.

TestDisjunctionMaxQueryMaxScoreIOException > testGetMaxScoreIOExceptionIsPropagated FAILED
    junit.framework.AssertionFailedError: Unexpected exception type, expected IOException but got java.lang.RuntimeException: java.io.IOException: getMaxScore failed
        at org.apache.lucene.search.TestDisjunctionMaxQueryMaxScoreIOException.testGetMaxScoreIOExceptionIsPropagated(TestDisjunctionMaxQueryMaxScoreIOException.java:108)

        Caused by:
        java.lang.RuntimeException: java.io.IOException: getMaxScore failed
            at org.apache.lucene.search.DisjunctionScoreBlockBoundaryPropagator.lambda$static$0(DisjunctionScoreBlockBoundaryPropagator.java:40)
            at java.base/java.util.Comparator.lambda$comparing$77a9974f$1(Comparator.java:473)
            ...
            at java.base/java.util.Arrays.sort(Arrays.java:1230)
            at org.apache.lucene.search.DisjunctionScoreBlockBoundaryPropagator.<init>(DisjunctionScoreBlockBoundaryPropagator.java:54)
            at org.apache.lucene.search.DisjunctionMaxScorer.<init>(DisjunctionMaxScorer.java:53)
            at org.apache.lucene.search.DisjunctionMaxQuery$DisjunctionMaxWeight$1.get(DisjunctionMaxQuery.java:158)
            ...
            at org.apache.lucene.search.IndexSearcher.search(IndexSearcher.java:624)

            Caused by:
            java.io.IOException: getMaxScore failed
                at org.apache.lucene.search.TestDisjunctionMaxQueryMaxScoreIOException$1$1$1.getMaxScore(TestDisjunctionMaxQueryMaxScoreIOException.java:60)
                at org.apache.lucene.search.DisjunctionScoreBlockBoundaryPropagator.lambda$static$0(DisjunctionScoreBlockBoundaryPropagator.java:38)

• The declared contract. Scorer.getMaxScore(int) declares IOException (Scorer.java:79), as do IndexSearcher.search(Query, int) (IndexSearcher.java:623) and the propagator's constructor (DisjunctionScoreBlockBoundaryPropagator.java:49).
• Same method, two answers. The constructor lets advanceShallow (:52) and the identical getMaxScore(NO_MORE_DOCS) call at :58 throw IOException unchanged; only the copy inside the comparator wraps it. A lambda cannot throw a checked exception, so the comparator had to adapt it somehow; nothing in the introducing PR, the javadoc or the tests suggests that changing the type was meant (an inference from the record).
• History. Before the class existed, 8.2.0 surfaced the same failure as the declared IOException (thrown via DisjunctionMaxScorer.getMaxScore). The introducing PR (apache/lucene-solr#791) and its issue (#9965) never discuss exceptions; no javadoc, CHANGES entry or test documents the wrap.
• Project practice. #12516 (its CHANGES entry: "Unwrap and throw execution exceptions cause when performing concurrent search") made concurrent search throw the original exception, as the sequential path does. lucene/MIGRATE.md:526-527 asks for UncheckedIOException for I/O left inside reader getters that no longer declare IOException (#16057): a precedent for the unchecked wrapper type, not a project-wide rule.

The case for "intended": wrapping a checked exception in a Comparator is a common Java idiom; Query, Weight and Scorer are expert APIs; core wraps IOException in RuntimeException elsewhere (for example DirectReader's LongValues.get, util/packed/DirectReader.java:199-205); the cause is kept and the failure is loud. So this is at most a cleanup, and #12516 itself was filed under "Changes in runtime behavior", not "Bug Fixes".

Why it fails as an intent argument: those other wraps sit behind signatures that cannot throw IOException; here the enclosing constructor declares it and already throws it for the same call (:58). The argument bounds the value of a fix, not whether the behaviour is intended. The cross-model reviewer (OpenAI GPT-5.6) rated it moderate; every checker agreed it limits the priority only.

Both options were validated with gradle in a clean scratch worktree of 5adff78bb168 (OpenJDK 25.0.3, seed DEADBEEF, 2026-11-03): stock, the repro fails with assertions on and off; with either fix it passes, on and off.

Replace MAX_SCORE_COMPARATOR with a loop that reads getMaxScore(NO_MORE_DOCS) once per clause into maxScores, then sort the scorers and their scores together with an InPlaceMergeSorter: by Float.compare of the stored score, then by cost, as today (both sorts are stable, so the order is unchanged). getMaxScore runs outside any lambda, so its IOException propagates as declared. The Arrays and Comparator imports go.

Scorer[] scorerArray = scorers.toArray(Scorer[]::new);
for (Scorer scorer : scorerArray) {
  scorer.advanceShallow(0);
}
float[] maxScoreArray = new float[scorerArray.length];
for (int i = 0; i < scorerArray.length; ++i) {
  maxScoreArray[i] = scorerArray[i].getMaxScore(DocIdSetIterator.NO_MORE_DOCS);
}
new InPlaceMergeSorter() {
  @Override
  protected int compare(int i, int j) {
    int cmp = Float.compare(maxScoreArray[i], maxScoreArray[j]);
    if (cmp == 0) {
      cmp = Long.compare(scorerArray[i].iterator().cost(), scorerArray[j].iterator().cost());
    }
    return cmp;
  }

  @Override
  protected void swap(int i, int j) {
    ArrayUtil.swap(scorerArray, i, j);
    float tmp = maxScoreArray[i];
    maxScoreArray[i] = maxScoreArray[j];
    maxScoreArray[j] = tmp;
  }
}.sort(0, scorerArray.length);
this.scorers = scorerArray;
this.maxScores = maxScoreArray;

Trade-offs

A slightly larger diff than the alternative (+29/-20 lines against +7/-2). It changes how often and when getMaxScore is called: once per clause, before the sort, instead of during the sort (in each comparison the clause takes part in) plus once more after it; the regression test covers the exception path. No benchmark was run.

What the checks validated

• Stock 5adff78bb168: the repro fails through gradle with assertions on and off; with this fix it passes, on and off.
• With the fix, the repro plus TestDisjunctionMaxQuery, TestLogOddsFusionQuery and TestDisjunctionScoreBlockBoundaryPropagator: 65 tests, 0 failures, 0 skipped.
• :lucene:core:check -x test (format, lint, forbidden APIs) with the fix and the test: passes.

The smallest change: in the lambda, throw new UncheckedIOException(e) instead of new RuntimeException(e), and wrap Arrays.sort in try { ... } catch (UncheckedIOException e) { throw e.getCause(); }.

-                  throw new RuntimeException(e);
+                  throw new UncheckedIOException(e);
 ...
-    Arrays.sort(this.scorers, MAX_SCORE_COMPARATOR);
+    try {
+      Arrays.sort(this.scorers, MAX_SCORE_COMPARATOR);
+    } catch (UncheckedIOException e) {
+      throw e.getCause();
+    }

Trade-offs

Keeps the comparator and its repeated getMaxScore calls. An UncheckedIOException that a scorer itself throws during the sort would also be rethrown as its checked cause, a small behaviour change of its own; the recommended fix has no such collision.

What the checks validated

• The repro passes through gradle with assertions on and off; the repro plus the same 3 disjunction suites: 65 tests, 0 failures (:lucene:core:check not run for this option). The hunt's own runs of this change agree (63 and 64 tests in their suite runs).

Method: semi-formal (a proof-obligation audit of a class's contract, witnessed by an executable repro).

• The obligation: the constructor declares IOException, so an IOException from any scorer call it makes should reach the caller as IOException. advanceShallow (:52) and the post-sort getMaxScore (:58) meet it; the comparator's getMaxScore (:38-40) does not.
• A JUnit test witnessed it on main (assertions on and off) and on 10.6.0 and 10.0.0. An independent reproducer and an executed review by another model family (OpenAI GPT-5.6) wrote their own tests from the claim alone; a devil's-advocate verifier and the adjudication re-ran the finder's test; the one-test repro shipped here was then cut to its minimum.