CachingCollector#replay lets CollectionTerminatedException escape instead of ending only the current segment, as IndexSearcher does

CachingCollector records the hits of a first search so that replay(other) can feed them to a second collector instead of re-running the query; CachingCollectorManager (new in 10.6.0) does the same per slice and then reduces. A leaf collector may end a segment early by throwing CollectionTerminatedException, which LeafCollector#collect documents as the per-segment stop signal and IndexSearcher.searchLeaf catches, both from getLeafCollector and from scoring (IndexSearcher.java:835-855 on main 645d4fe14a20). The replay loops have no such catch (CachingCollector.java:115, :100-102, :151-154), so the exception escapes replay, without a stack trace, and the remaining segments are never replayed. A stock TopFieldCollector sorted by the index sort throws it once it has counted more hits than its threshold (1,000 by default; one segment with that many is enough): replaying a two-segment index-sorted cache into it throws, and catching the exception returns the top 10 ts 1000..1009 instead of 0..9. It has been there since the exception was added in 4.3.0 (LUCENE-4862, 2013) and affects every release to 10.6.0 and main (13 releases and main executed, the others by source history). Catching the exception per segment in replay, as IndexSearcher does, fixes it; the core caching tests, the grouping module and the whole core module pass with the fix.

1. IndexSearcher.searchLeaf (IndexSearcher.java:831-863) wraps collector.getLeafCollector(ctx) in try and returns on the exception (:835-841, "there is no doc of interest in this reader context"), wraps scoring in try and falls through on it (:849-855, "collection was terminated prematurely"), then calls leafCollector.finish() (:862).
2. CachingCollector#replay (CachingCollector.java:106-118) calls other.getLeafCollector(context) (:115) and collect(collector, i) (:116) for each cached segment. collect loops over the cached doc IDs and calls collector.collect(doc) (:100-102, then finish() at :103); with cached scores, ScoreCachingCollector#collect runs the same loop with the score set (:151-154) but never calls finish() (LFV-180). There is no try anywhere, so the exception from either call leaves replay and the loop over segments stops.
3. CachingCollectorManager#replay (CachingCollectorManager.java:118-130) creates one second-pass collector per slice, calls cache.replay(...) (:126) and then reduce(...) (:129). An exception in the first slice skips the other slices and the reduce.

• TopFieldCollector (TopFieldCollector.java:92-103): when the search sort is part of the index sort and a document is not competitive, if (totalHits > totalHitsThreshold) throw new CollectionTerminatedException(); (:98-100). IndexSearcher#search(Query, int, Sort) passes TOTAL_HITS_THRESHOLD = 1000 (IndexSearcher.java:100, :733). On upstream main after #16857 (merged 2026-10-29) the same throw sits in IndexSortedLeafFieldComparator.
• MultiCollector throws it from getLeafCollector when no child wants the segment (MultiCollector.java:142-143) and from collect once every child has stopped (:218-226).
• Any custom collector, as the exception's javadoc invites: "Throw this exception in LeafCollector#collect(int) to prematurely terminate collection of the current leaf" (CollectionTerminatedException.java:19-21).

The exception is stackless: fillInStackTrace is overridden because it is "never re-thrown" (CollectionTerminatedException.java:35-39), so the trace shows Caused by: org.apache.lucene.search.CollectionTerminatedException with no frames. Catching it around replay leaves the later segments unreplayed: in the index-sort example the top 10 are ts 1000..1009 instead of 0..9.

• Opt-in. CachingCollector and CachingCollectorManager are @lucene.experimental expert APIs (CachingCollector.java:38, CachingCollectorManager.java:48). Within that usage the defaults suffice: the index-sort example needs only a segment with more than 1,000 hits.
• Loud by default. The request fails with a stackless runtime exception. Results are silently wrong only if the caller catches it around CachingCollector#replay: the second-pass collector it holds misses every segment after the first stopped one. Around CachingCollectorManager#replay a catch leaves no result at all, because the later slices and reduce() are skipped (CachingCollectorManager.java:123-129).
• Deterministic. Same result with assertions on and off, with a sequential IndexSearcher; nothing is written or corrupted.
• Not affected. GroupingSearch, the only in-tree replay user (GroupingSearch.java:209): its second-pass collectors use Integer.MAX_VALUE thresholds (TopGroupsCollector.java:134, :142) and never stop early (read, not executed). Solr's grouping cache likewise, by code reading.
• Workaround. A second pass with a totalHitsThreshold of Integer.MAX_VALUE never throws (totalHits > totalHitsThreshold, TopFieldCollector.java:98, never holds), as in GroupingSearch; replay then feeds it every cached hit instead of stopping early. Or re-run the search instead of replaying (read, not executed).
• Likelihood: rare. Nobody reported it in the 13 years since 4.3.0.

The test sits in org.apache.lucene.search, as Lucene's own tests do, but uses only public API. It uses the deprecated IndexSearcher#search(Query, Collector) because CachingCollector is a Collector; the manager form exists only from 10.6.0 on. It compiles against 10.5.2, 10.6.0 and main; 9.12.3 has no MatchAllDocsQuery.INSTANCE, so on older releases write new MatchAllDocsQuery().

The collector throws on its first hit, so one document is enough. The comment line in the catch states the expectation: IndexSearcher.search with the same collector ends the segment and returns. The realistic trigger is the two-segment index-sort example in "The finding in 30 seconds"; it is described there, not added as a second test.

cp $REPRO/TestCachingCollectorReplayTerminatedLeaf.java $LUCENE/lucene/core/src/test/org/apache/lucene/search/
cd $LUCENE && ./gradlew :lucene:core:test --tests TestCachingCollectorReplayTerminatedLeaf -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off fails the same way: -Ptests.asserts=false

TestCachingCollectorReplayTerminatedLeaf > testReplayIntoCollectorThatTerminatesLeaf FAILED
    java.lang.AssertionError: CachingCollector.replay let org.apache.lucene.search.CollectionTerminatedException escape
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:F0069F7D7DA18069]:0)
        at org.apache.lucene.search.TestCachingCollectorReplayTerminatedLeaf.testReplayIntoCollectorThatTerminatesLeaf(TestCachingCollectorReplayTerminatedLeaf.java:54)

        Caused by:
        org.apache.lucene.search.CollectionTerminatedException
> Task :lucene:core:test FAILED

# the same with -Ptests.asserts=false; the cause has no frames (the exception is stackless)

• Contract. LeafCollector#collect: "The collection of the current segment can be terminated by throwing a CollectionTerminatedException. In this case, the last docs of the current LeafReaderContext will be skipped and IndexSearcher will swallow the exception and continue collection with the next leaf" (LeafCollector.java:76-79). LeafCollector#finish runs once the leaf "has finished collecting successfully, including when a CollectionTerminatedException is thrown" (:150-151), which reads as an obligation of whoever drives the leaf; the no-score replay calls finish() itself (CachingCollector.java:103; the scored replay does not, LFV-180). These javadocs name IndexSearcher, so applying them to replay is an inference from the collector protocol, not an explicit guarantee.
• Replay replaces a search. CachingCollector: if the cache overflowed, "you must instead re-run the original search" (CachingCollector.java:25-31); CachingCollectorManager: "replayed to a second-pass CollectorManager without re-running the query" (CachingCollectorManager.java:24-27). The replay javadocs list what differs (no scorer without cached scores) and what they throw (IllegalStateException): CachingCollector.java:345-354, CachingCollectorManager.java:113-117. CachingCollector#replay also keeps a stale @throws IllegalArgumentException about out-of-order collection (:351-352; out-of-order scoring was removed in 5.0.0, LUCENE-6179, and replay never throws it). This exception is not among them.
• The core drivers handle it. IndexSearcher (IndexSearcher.java:835-855), MultiCollector (MultiCollector.java:128-134, :218-226) and, since #12609, SuggestIndexSearcher (SuggestIndexSearcher.java:74-77). Not every in-tree driver does: SortRescorer and grouping's BlockGroupingCollector run only collectors they build with Integer.MAX_VALUE thresholds and have no catch (the reason jpountz gave on #12380, next point); the sandbox PostCollectionFaceting, which like replay feeds already-collected documents to collectors the caller supplies, has no catch either; and DrillSidewaysScorer.java:149-151 has an open TODO about the exception. (Read only; none of these was executed or is claimed as a bug.)
• Precedent. LUCENE-6326 / LUCENE-6772 (#7387, #7830) fixed MultiCollector in 5.4. Before #12609, jpountz had explained on #12380 (2023-09-28) that SuggestIndexSearcher skipped the catch around getLeafCollector only because, "unlike IndexSearcher which may run any Collector", it runs a collector "which never throws a CollectionTerminatedException", and offered to approve the change; replay(Collector other) accepts any collector. LUCENE-6337 (#7398) reported the same omission in ToParentBlockJoinIndexSearcher; it was never fixed and is still open, and the class was removed in 2017 (LUCENE-6959).
• No recorded decision. LUCENE-4862 created the exception and taught only IndexSearcher (its commit touches CHANGES.txt, CollectionTerminatedException.java, Collector.java, IndexSearcher.java and a test); its comments never mention CachingCollector. No commit ever added or removed a handler in replay, and no upstream test combines replay with the exception.

Strongest case (the intended-behaviour check, the cross-model review and the review, each rating it at most moderate): the exception's javadoc says IndexSearcher swallows it and that you should not catch it when calling IndexSearcher's methods (CollectionTerminatedException.java:23-25), so the contract could bind IndexSearcher only and let other drivers' callers catch it; the APIs are @lucene.experimental; and replay is a lean pump that also skips setWeight and the competitive iterator.

Why it fails: catching it outside replay is not a correct use, because replay has already abandoned the remaining segments ([1000..1009] instead of [0..9]). The steps replay skips are optional by design (competitiveIterator "Optionally returns", setWeight a default no-op), while the exception is the one stop signal LeafCollector#collect documents. Experimental status allows API changes, not a driver that breaks the collector protocol, and nothing documents a "no early-terminating collectors" precondition. A documentation-only resolution is possible, but wherever upstream resolved this omission in another driver, it fixed the code (LUCENE-6772, #12609) and never documented a limitation instead; LUCENE-6337 stayed open until its searcher was removed in 2017. Conceded: the javadocs do not promise IndexSearcher's semantics for replay in so many words, and an Integer.MAX_VALUE threshold avoids the stock trigger.

Two options were built and run in a scratch worktree of 645d4fe14a20; a documentation-only change is not recommended. LFV-180 (the missing finish() in the scored replay and in the wrapped first pass) touches the same method, so option B combines both.

Three try/catch blocks in CachingCollector.java that mirror the two catches of IndexSearcher.java:835-855: an exception from other.getLeafCollector(context) skips that segment (no leaf collector, so no finish(), as IndexSearcher returns); an exception from the no-score collect loop ends the segment and the existing collector.finish() still runs; an exception from the scored loop ends the segment. It is not fully equivalent to IndexSearcher on the scored replay: segments there still end without finish() (LFV-180, option B), and setScorer stays outside the catch.

// NoScoreCachingCollector#replay
final LeafCollector collector;
try {
  collector = other.getLeafCollector(context);
} catch (CollectionTerminatedException _) {
  // there is no doc of interest in this reader context
  // continue with the following leaf
  continue;
}
collect(collector, i);
// both collect(...) loops (no-score loop shown)
try {
  for (int doc : docs) {
    collector.collect(doc);
  }
} catch (CollectionTerminatedException _) {
  // collection of this leaf was terminated early, continue with the following leaf
}

Trade-offs

• Behaviour change. A caller that catches the exception around replay today gets the complete result instead of a truncated one; no documented contract supports relying on the escape, which is undocumented and stackless.
• setScorer. The scored replay calls setScorer before the try; in IndexSearcher it runs inside scorer.score(...), under the catch. Moving it into the try would mirror that exactly; LeafCollector#setScorer does not document the exception, so it was left out (not built).
• finish() on the scored replay is still missing: that is LFV-180 (option B).
• Cost. One try per segment, nothing per document. Conflict. Open PR #15210 edits other lines of the file.

What the checks validated

• Stock: the minimal test fails with assertions on and off. With the fix: it passes with assertions on and off, and the index-sort scenario passes 2 of 2 (top 10 ts 0..9).
• TestCachingCollector, TestCachingCollectorManager, TestMultiCollector, TestMultiCollectorManager, TestIndexSearcher (39 tests with the new one, 1 skipped) and the whole grouping module (56 tests): 0 failures, assertions on and off. The whole core module: 748 classes, 8,897 tests, 0 failures, 322 skipped (748 is the number of core Test*.java files, so no copied test ran).
• ecjLint and forbiddenApis (main and test) pass; checkGoogleJavaFormat passes for CachingCollector.java and asks only to wrap the test's 105-column comment line.

Option A plus collector.finish() after the scored replay's try/catch, so both replay paths end every replayed segment with finish() "including when a CollectionTerminatedException is thrown" (LeafCollector.java:150-151), plus super.finish() in NoScoreCachingLeafCollector#finish (LFV-180's fix for the wrapped first pass). +24/-7 in one file.

Trade-offs

One PR for two issues; reviewers may prefer them separate.

What the checks validated

This doc's test, LFV-180's TestCachingCollectorFinish (facet), the closest core suites (39 tests, 1 skipped) and the grouping module (56 tests) pass with assertions on. The whole core module was run for option A only.

A javadoc note such as "replay does not support collectors that throw CollectionTerminatedException".

Trade-offs

Rules out an index-sorted TopFieldCollector's early termination in a second pass: callers would have to turn it off with an Integer.MAX_VALUE threshold or re-run the search, since catching the exception gives wrong hits. It also contradicts LeafCollector#collect.

Method: bounded-exhaustive translation validation (semi-formal). The harness of a hunt unit (concurrent collector managers) runs the real collector managers on every index of 1-3 segments x 1-6 documents (258 shapes) under every distinct IndexSearcher slicing (3,750), sequentially and with a 3-thread pool, and compares each result with a plain IndexSearcher.search. Among its CachingCollectorManager checks, the failure kind "replay into TopFieldCollectorManager(INDEXORDER, 1, 0) threw CollectionTerminatedException" appeared 271,021 times in the run with assertions on, in every slicing. The finder reduced it to a one-segment public-API JUnit on the stock main jars and a release-compatible SimpleCollector variant; this doc's test is a one-document, one-method version of those.