matchhighlight PassageSelector sizes its passage queue by maxPassages before it looks at any match, so maxPassages = Integer.MAX_VALUE throws

PassageSelector.pickBest(value, markers, maxPassageWindow, maxPassages) picks the best highlight passages of a field value; MatchHighlighter reaches it through FieldValueHighlighters.highlighted, which passes maxPassages on unchanged. Before it reads a single match, pickBest builds its PriorityQueue with Math.max(16, maxPassages) slots, and PriorityQueue allocates maxSize + 1 slots up front and rejects any maxSize of 2,147,483,631 or more. So maxPassages = Integer.MAX_VALUE (meant as "all passages") throws IllegalArgumentException on every call with a non-empty value and a non-zero window, even for one match, where maxPassages = 10 returns the one passage. Everywhere else in the method maxPassages only caps the result, and the queue never receives more passages than there are (split) matches, so the extra capacity never changes the result. Large values below the limit work but allocate in proportion to maxPassages: 64 MiB per call at 2^24 for one match. The sizing came with the class in 2020, so every release that ships matchhighlight (9.0.0 to 10.6.0) and main is affected. Default settings; the failure is loud and results are never wrong.

• Entry points. PassageSelector.pickBest(value, markers, maxPassageWindow, maxPassages) (PassageSelector.java:67-74) delegates to the five-argument overload (:76-84). Neither has javadoc. FieldValueHighlighters.highlighted(maxPassageWindow, maxPassages, formatter, matchFields) (FieldValueHighlighters.java:88-115) does not document maxPassages and passes it unchanged to pickBest (:109-110). No argument is validated.
• The pre-size. After the early return for an empty value or a zero window (:87-89): int pqSize = Math.max(16, maxPassages); (:93), then PriorityQueue<Passage> pq = PriorityQueue.usingComparator(pqSize, passageScorer); (:96), and only then markers = splitOrTruncateToWindows(...) (:98).
• PriorityQueue. The class javadoc says it "pre-allocates an array of length {@code maxSize+1}" (PriorityQueue.java:34-35; the class is @lucene.internal). The constructor throws IllegalArgumentException("maxSize must be >= 0 and < " + ArrayUtil.MAX_ARRAY_LENGTH + ...) for maxSize >= ArrayUtil.MAX_ARRAY_LENGTH ("Throw exception to prevent confusing OOME", :121-125), otherwise allocates new Object[maxSize + 1] (:129-134). MAX_ARRAY_LENGTH is Integer.MAX_VALUE - NUM_BYTES_ARRAY_HEADER, 2,147,483,631 on the tested JVM.
• maxPassages is otherwise only a cap. The selection loop makes at most one insertWithOverflow per split marker (:103-166, insert at :158); the result is clamped by last = Math.min(last, maxPassages); (:213); with no candidate, pickDefaultPassage stops at defaultPassages.size() >= maxPassages (:289). So once the queue can hold every split marker, more capacity cannot change the result.

The no-match column matters only for direct pickBest callers: highlighted formats only fields that have matches (FieldValueHighlighters.java:97-98). End to end, MatchHighlighter with highlighted(20, 10, ...) returns [>lucene< search], and with Integer.MAX_VALUE the same IllegalArgumentException escapes MatchHighlighter.highlight (FieldValueHighlighters.java:109, MatchHighlighter.java:266).

• What goes wrong. Integer.MAX_VALUE (anything from 2,147,483,631 up) fails every pickBest call on a non-empty value with a non-zero window, even when nothing matches, and so every MatchHighlighter call on a document with a match in a highlighted field (a field without a match never reaches pickBest). The message names the internal queue size, not the argument the caller passed.
• Large accepted values. They return the right passages but allocate about 4 bytes per unit of maxPassages on every call (64 MiB at 2^24); with a 1 GiB heap, 3*10^8, 10^9 and 2^31 - 18 end in OutOfMemoryError (3*10^8 and 10^9 pass with 4 GiB; 2^31 - 18 also runs out with 2 GiB). Concurrent calls multiply the allocation.
• Scale. None needed: one 13-character value with one match. Fixed input, assertions on or off.
• Workaround. Pass a finite count. Once maxPassages is at least the number of matches (counted after splitting at value boundaries) and the number of field values, a larger value changes nothing.
• How likely: rare. A code search found no use of matchhighlight's PassageSelector in Solr or Elasticsearch; Integer.MAX_VALUE fails on the first call, so a developer meets it in testing and picks a finite count; no public report was found in the documented searches since the class shipped in 9.0.0.

Copy the test into lucene/highlighter/src/test/org/apache/lucene/search/matchhighlight/ of a Lucene checkout and run it with gradle (command below). It is in the matchhighlight package like the upstream tests and uses only public API.

Executed: gradle on a clean 645d4fe14a20 (fails) and with fix A (passes); the standalone runner on the stock main jars with -ea and -da (fails; passes with the fix), on the 10.6.0 jars (-ea) and on 10.5.2 and 9.12.3 (-da): all fail with the same IllegalArgumentException. Seeds tried: DEADBEEF, 5EED1234. The exception does not depend on the heap size: the PriorityQueue guard runs before any allocation. On 10.6.0 and older the frame below PriorityQueue.<init> is PassageSelector$1.<init>(PassageSelector.java:97), because those releases build an anonymous PriorityQueue subclass (main uses PriorityQueue.usingComparator since #14705).

cp $REPRO/TestPassageSelectorMaxValueMaxPassages.java $LUCENE/lucene/highlighter/src/test/org/apache/lucene/search/matchhighlight/
cd $LUCENE && ./gradlew :lucene:highlighter:test --tests org.apache.lucene.search.matchhighlight.TestPassageSelectorMaxValueMaxPassages -Ptests.seed=DEADBEEF

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF (module prefixes trimmed)
> Task :lucene:highlighter:test FAILED

TestPassageSelectorMaxValueMaxPassages > testMaxValueMaxPassages FAILED
    java.lang.IllegalArgumentException: maxSize must be >= 0 and < 2147483631; got: 2147483647
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:C5AAB44B573F209A]:0)
        at org.apache.lucene.util.PriorityQueue.<init>(PriorityQueue.java:123)
        at org.apache.lucene.util.PriorityQueue.<init>(PriorityQueue.java:80)
        at org.apache.lucene.util.PriorityQueue.usingComparator(PriorityQueue.java:63)
        at org.apache.lucene.search.matchhighlight.PassageSelector.pickBest(PassageSelector.java:96)
        at org.apache.lucene.search.matchhighlight.PassageSelector.pickBest(PassageSelector.java:72)
        at org.apache.lucene.search.matchhighlight.TestPassageSelectorMaxValueMaxPassages.testMaxValueMaxPassages(TestPassageSelectorMaxValueMaxPassages.java:28)

:lucene:highlighter:test (FAILURE): 1 test, 1  failure
BUILD FAILED in 44s

# standalone runner, seed DEADBEEF
main 645d4fe14a20  -ea / -da   tests_run=1 failures=1   same IllegalArgumentException, PassageSelector.java:96
10.6.0             -ea         tests_run=1 failures=1   same, via PassageSelector$1.<init>(PassageSelector.java:97)
10.5.2, 9.12.3     -da         tests_run=1 failures=1   same, via PassageSelector$1.<init>(PassageSelector.java:97)
main + fix A       -ea / -da   tests_run=1 failures=0

• Cap semantics. last = Math.min(last, maxPassages) (PassageSelector.java:213) and defaultPassages.size() >= maxPassages (:289) work at Integer.MAX_VALUE; the queue cannot receive more entries than there are split markers (:103-166).
• The other "max" argument, meant to accept Integer.MAX_VALUE. LUCENE-10135 (#334, Dawid Weiss, 2021, in 9.0.0) fixed an overflow for a huge maxPassageWindow, and the upstream test TestPassageSelector.largeWindow passes Integer.MAX_VALUE as the window (TestPassageSelector.java:159-162). A residual window-shift overflow at that window, for permitted ranges after offset 0, is a separate, already known bug.
• Package convention. MatchRegionRetriever's maxHitsPerField: "The predicate should return {@link Integer#MAX_VALUE} for all hits to be considered" (MatchRegionRetriever.java:230-233).
• The module's other passage API. The UnifiedHighlighter documents maxPassages as "The maximum number of top-N ranked passages" (UnifiedHighlighter.java:757) and bounds its queue with Math.min(64, maxPassages + 1) (FieldHighlighter.java:143; its own wrap at Integer.MAX_VALUE is a separate bug).
• Tests. Upstream TestPassageSelector uses maxPassages from 1 to 100 (100 in checkEmptyExtra, checkOddOverlaps and defaultPassages, TestPassageSelector.java:40, :48, :57, :69, :195; randomIntBetween(1, 10) in its random test, :322); nothing says large values are unsupported.
• History. The class was created in 2020 with new PriorityQueue<>(maxPassages), when the queue capacity was the only cap on the result. #11990 (Alan Woodward, 2022, 9.5.0) added the explicit clamp at :213. In that review Dawid Weiss wrote that capping the queue at the requested maximum was "a deliberate decision ... so that regardless of how many markers there are, the overhead of the pq remains fairly low" and suggested min(markers.size(), maxPassages * 3); Alan Woodward proposed the floor of 16 instead, and it was merged. Large maxPassages was never discussed.
• Precedent. LUCENE-2119 (2009), opened by Michael McCandless about IndexSearcher.search(q, Integer.MAX_VALUE): "This trips users up fairly often because they assume our PQ doesn't statically pre-allocate (a reasonable assumption...)". The fix capped the count at maxDoc in the layer that knew the real bound; here pickBest knows it, the number of split markers.

The strongest case for "works as designed" (a reviewer from another model family and an intended-behaviour devil's advocate): sizing by maxPassages was a deliberate #11990 choice to keep queue overhead low; PriorityQueue documents its pre-allocation, and SOLR-5661 added its size guard on purpose so that impossible sizes fail loudly; core top-N collectors (new TopScoreDocCollectorManager(Integer.MAX_VALUE, ...)) and the classic Highlighter.getBestFragments(..., Integer.MAX_VALUE) fail the same way; and nothing documents maxPassages at all.

Why it fails: the stated goal was low overhead, and the fix is never larger than today's queue; the pre-allocation note sits on a @lucene.internal class that a pickBest caller is not expected to read; for the core collectors, IndexSearcher itself caps the count at Math.max(1, maxDoc) before it builds the collector manager (IndexSearcher.java:588-599; search(q, Integer.MAX_VALUE) returns 1 hit where a direct TopScoreDocCollectorManager(Integer.MAX_VALUE, ...) throws), the layer that knows the bound applies it, and here that layer is pickBest, which already holds every marker; and the same method and package treat Integer.MAX_VALUE as a legal "no limit" value. The argument bears on priority (a Low robustness fix), not on whether the call should work. A maintainer may still prefer a javadoc note (see Suggested fix).

Three options. Option A was validated with gradle in a scratch worktree at 645d4fe14a20 and by translation validation against the stock class; B and C were not executed. Credit: the shape of A (bound the queue by the marker count) is what Dawid Weiss suggested in the #11990 review; the floor of 16 it keeps is Alan Woodward's.

In PassageSelector.pickBest, move markers = splitOrTruncateToWindows(...) (:98) above the queue and compute pqSize = Math.max(16, Math.min(maxPassages, markers.size())) instead of Math.max(16, maxPassages) (:93).

markers = splitOrTruncateToWindows(markers, maxPassageWindow, permittedPassageRanges);

// minimum priority queue size of 16 so that small maxPassages values don't
// return too few passages due to subsequent passage merges. At most one passage
// is collected per (split) marker, so the queue never needs to be larger than that.
int pqSize = Math.max(16, Math.min(maxPassages, markers.size()));

// Best passages so far.
PriorityQueue<Passage> pq = PriorityQueue.usingComparator(pqSize, passageScorer);

Trade-offs

• No change in results for any maxPassages the current code accepts: with capacity at least the number of split markers nothing is ever evicted, and below that the size is unchanged (for valid inputs; by a hand proof, not published).
• The queue is never larger than today's (unchanged when maxPassages <= markers.size() or when both sizes are the floor of 16, smaller otherwise), so it keeps the low-overhead goal of #11990. The split does the same work, only earlier. No API change.
• Use the count after the split: a match that crosses value boundaries becomes several markers, and a variant using the caller's markers.size() loses passages.
• Headroom like the maxPassages * 3 from the #11990 review must avoid int overflow: it wraps negative for maxPassages > 715,827,882.

What the checks validated

• Gradle, scratch worktree at 645d4fe14a20, JDK 25, -Ptests.seed=DEADBEEF: without the fix the minimal test fails; with it, :lucene:highlighter:checkGoogleJavaFormat :lucene:highlighter:test is BUILD SUCCESSFUL: 35 suites, 723 tests, 0 failures, 0 errors, 0 skipped, among them TestPassageSelector 20/20, TestMatchHighlighter 6/6, TestMatchRegionRetriever 22/22 and the minimal test 1/1 (the fixed main source was recompiled; the test classes, which the fix does not touch, were up to date from the unfixed run).
• The standalone runner with the fixed class shadowed on the stock main jars: the minimal test passes with -ea and -da; the allocation probe returns the same passage with 552 bytes allocated for every maxPassages up to Integer.MAX_VALUE.
• Translation validation of the stock class against this variant on the stock jar: 31,086,300 checks with assertions off and 24,980,382 on, 0 failures on the sampled maxPassages values (0 to 20, around the bound beyond which the result cannot change, 4096, three random values below it, and 2^30, Integer.MAX_VALUE - 1 and Integer.MAX_VALUE); that the results are equal for every value rests on the hand proof (not published), not on the run; all three mutants of the fix (pre-split count, no floor, off by one) were killed.

Clamp the value in the convenience factory before it calls pickBest.

Trade-offs

Fixes the MatchHighlighter path but not direct pickBest callers, and the factory does not know the split marker count. Not recommended; not executed.

A javadoc note on both pickBest overloads and on highlighted that maxPassages, a positive count, is allocated up front and must stay below 2^31 - 17.

Trade-offs

No behaviour change; turns the "all passages" idiom into a documented error and keeps the memory cost of large values. A fallback if maintainers reject A; not executed.

Method: executed differential testing with a hand proof (no formal model), in a hunt round on numeric limits of public API arguments, on the stock main jars.

• First signal. A planning probe called pickBest(value, markers, 20, Integer.MAX_VALUE - 1) on a text with two matches: IllegalArgumentException, where n = 1000 returns 2 passages; n = 10^8 allocated 381 MiB (main a9779ef3c193, 2026-10-28).
• Proof and check. The finder wrote down why the result cannot depend on the queue capacity once it covers the split markers (at most one insert per marker, the clamp, the default path), then checked it on the stock jar by bounded-exhaustive plus seeded-random translation validation against the fixed variant and three mutants of it: 31,086,300 checks with assertions off, 24,980,382 on, 0 failures, all mutants killed. The Integer.MAX_VALUE failure appeared on all 693,640 inputs with a non-empty value and a non-zero window.
• Reduction. A public-API JUnit test, later the single test shown here.