UnifiedHighlighter with maxNoHighlightPassages below -1 throws 'Illegal Capacity' when a document's field text has no match, although the javadoc says any value below 0 falls back to maxPassages

When a document is a hit but nothing in the highlighted field matches, the UnifiedHighlighter returns a default summary: the field's first sentences. The javadoc of getMaxNoHighlightPassages says how many: "If it's less than 0 (the default) then this defaults to the maxPassages parameter given for each request. If this is 0 then the resulting highlight is null (not formatted)." (UnifiedHighlighter.java:634-639 on main 645d4fe14a20). The code maps only exactly -1, the default: getSummaryPassagesNoHighlight(maxNoHighlightPassages == -1 ? maxPassages : maxNoHighlightPassages) (FieldHighlighter.java:91-93). Any other negative value is used as the sentence count, and in the stock implementation the list allocation at the top of getSummaryPassagesNoHighlight, new ArrayList<>(Math.min(maxPassages, 10)) (:112, right after an assert), throws IllegalArgumentException: Illegal Capacity: -2 from the JDK. With withMaxNoHighlightPassages(-2), Integer.MIN_VALUE, the deprecated setter or an override of the protected getter, every highlight call that includes a document whose field has text but no match fails, with assertions on and off; in a multi-field call the other fields lose their snippets too. Documents with a match are highlighted normally. The check, the capacity line and the javadoc all came in the first UnifiedHighlighter commit (LUCENE-7438, 2016); every release from 6.3.0 to 10.6.0 and main is affected. A one-character change, < 0 instead of == -1, fixes it.

• Where the value comes from. The default is DEFAULT_MAX_HIGHLIGHT_PASSAGES = -1 (UnifiedHighlighter.java:116). Builder#withMaxNoHighlightPassages(int) stores any int, with no check and no javadoc (:401-404), as does the deprecated setMaxNoHighlightPassages (:216-219). The protected getMaxNoHighlightPassages(String field) returns it (:640-642) under the contract quoted above (:634-639), and getFieldHighlighter passes it to each FieldHighlighter (:1138).
• The sentinel check. FieldHighlighter.highlightFieldForDoc returns null at once for empty content (FieldHighlighter.java:77-79; a document without a stored value is skipped earlier, UnifiedHighlighter.java:968-969); otherwise it scores passages (:86), and when none matched (:89) it calls getSummaryPassagesNoHighlight(maxNoHighlightPassages == -1 ? maxPassages : maxNoHighlightPassages) (:91-93). Only exactly -1 becomes maxPassages.
• The throw. The stock getSummaryPassagesNoHighlight(int maxPassages) (protected, :109-128) first asserts that the break iterator is at the start (:110; it is on the stock path, and the -ea runs pass it), then allocates new ArrayList<>(Math.min(maxPassages, 10)) (:112). Math.min(-2, 10) = -2, and the JDK's ArrayList(int) throws IllegalArgumentException("Illegal Capacity: -2").
• Why 0 and positive values work. Math.min(0, 10) = 0 gives an empty list, the loop while (passages.size() < maxPassages) (:115) does not run, and :96-99 returns null, the documented 0 behaviour; positive values collect that many sentences.
• Reach. highlight and highlightFields end in highlightFieldsAsObjects, whose loop calls highlightFieldForDoc (UnifiedHighlighter.java:987-988) with no per-field or per-document catch, so one unmatched document fails the whole call. highlightWithoutSearcher reaches the same method (:1105-1107).

• Who is hit. Code that configures the UnifiedHighlighter with a negative maxNoHighlightPassages other than -1: Builder#withMaxNoHighlightPassages, the deprecated setMaxNoHighlightPassages, or a subclass overriding the protected getMaxNoHighlightPassages hook; for example a developer who reads "less than 0 (the default)" and uses -2 or Integer.MIN_VALUE, or an application that forwards an unchecked configuration value.
• Default vs opt-in. The default (-1) works; the trigger is a non-default configuration value. Then, with the stock FieldHighlighter, any document whose field has text but no match triggers it, with any index and any offset source.
• What goes wrong. The call throws instead of returning the summary; in a multi-field call all fields lose their snippets. The message names a JDK list capacity, not the parameter. No wrong results, corruption or hang.
• Scale. None needed: one document, one call; deterministic, assertions on or off.
• Workaround. Use -1 for "same as maxPassages".
• How likely. Rare: someone has to pick a negative value other than -1, the failure is loud on the first unmatched document, and the recorded searches found no report in ten years.

Copy the test into lucene/highlighter/src/test/org/apache/lucene/search/uhighlight/ of a Lucene checkout and run it with gradle (command below). It uses StandardAnalyzer, ByteBuffersDirectory, a plain IndexWriterConfig and IndexSearcher, and no random(), so the outcome does not depend on the seed (LuceneTestCase still picks its default codec and locale from it). The IllegalArgumentException is caught only to rethrow it as the cause of an AssertionError that states expected vs actual; the cause keeps the ArrayList and FieldHighlighter frames. With the < 0 fix it passes unchanged, so it doubles as the regression test.

Executed: gradle on a clean 645d4fe14a20 (fails) and with the fix (passes); the standalone runner on the stock main jars with -ea and -da, and on the 10.6.0 release jars (fails, same cause); the minimization audit also ran a second seed (5 of 5 fail).

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

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF (the test as shown)
TestNegativeMaxNoHighlightPassages > testMinusTwoDefaultsToMaxPassages FAILED
    java.lang.AssertionError: maxNoHighlightPassages -2 (< 0): expected the default summary, got java.lang.IllegalArgumentException: Illegal Capacity: -2
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:9E98FFBEE072D62E]:0)
        at org.apache.lucene.search.uhighlight.TestNegativeMaxNoHighlightPassages.testMinusTwoDefaultsToMaxPassages(TestNegativeMaxNoHighlightPassages.java:52)

        Caused by:
        java.lang.IllegalArgumentException: Illegal Capacity: -2
            at java.base/java.util.ArrayList.<init>(ArrayList.java:161)
            at org.apache.lucene.search.uhighlight.FieldHighlighter.getSummaryPassagesNoHighlight(FieldHighlighter.java:112)
            at org.apache.lucene.search.uhighlight.FieldHighlighter.highlightFieldForDoc(FieldHighlighter.java:92)
            at org.apache.lucene.search.uhighlight.UnifiedHighlighter.highlightFieldsAsObjects(UnifiedHighlighter.java:988)
            at org.apache.lucene.search.uhighlight.UnifiedHighlighter.highlightFields(UnifiedHighlighter.java:858)
            at org.apache.lucene.search.uhighlight.UnifiedHighlighter.highlightFields(UnifiedHighlighter.java:836)
            at org.apache.lucene.search.uhighlight.UnifiedHighlighter.highlight(UnifiedHighlighter.java:769)
            at org.apache.lucene.search.uhighlight.TestNegativeMaxNoHighlightPassages.testMinusTwoDefaultsToMaxPassages(TestNegativeMaxNoHighlightPassages.java:50)

# standalone runner, seed DEADBEEF
main 645d4fe14a20  -ea / -da   tests_run=1 failures=1   same cause
10.6.0             -ea         tests_run=1 failures=1   same cause

• The written contract covers every negative value. getMaxNoHighlightPassages: "If it's less than 0 (the default) then this defaults to the maxPassages parameter given for each request. If this is 0 then the resulting highlight is null (not formatted)." (UnifiedHighlighter.java:634-639). The setters have no javadoc of their own. The highlight javadoc promises the same fallback: "If no highlights were found for a document, the first maxPassages sentences from the field will be returned." (:759-761).
• Not a later narrowing. The javadoc sentence, the == -1 check and the capacity line all arrived in LUCENE-7438 (722e82712435, 2016-10-04); no test, CHANGES or MIGRATE entry restricts the sentinel to -1, and neither #8490 nor its review discusses other negative values.
• Intended rejection looks different. withMaxLength and setMaxLength reject bad values up front with "maxLength must be < Integer.MAX_VALUE" (:355-362, :191-199). Here nothing validates; the error is an incidental JDK capacity check, thrown late (only when an unmatched document is reached) and naming neither the parameter nor the cause.
• The same module treats a documented -1 as "any negative". TokenStreamFromTermVector documents "-1 disables the limit" and implements maxStartOffset < 0 ? Integer.MAX_VALUE : maxStartOffset (TokenStreamFromTermVector.java:83-87).
• Tests. Upstream tests pass only 0 (TestUnifiedHighlighter.java:843, TestUnifiedHighlighterTermIntervals.java:673) or the default; no test covers another negative value either way.

The strongest case for "works as designed" (the cross-model lenses, the independent reproducer, the devil's-advocate verifier and the adjudication): the default constant is exactly -1 and the check has been == -1 from the start; Solr's override returns exactly -1 (by code reading); the setters carry no javadoc; UnifiedHighlighter is @lucene.experimental and FieldHighlighter @lucene.internal; a negative sentence count other than -1 has no natural meaning; nobody reported it in ten years.

Why it fails: the only written description of the value explicitly covers every value below 0 and came in the same commit as the check; nothing in the code, tests or history says -1 alone; and even if -1 were meant to be the only sentinel, the result should be a clear up-front rejection, not a late JDK exception that only fires for unmatched documents and takes the other fields of the call down with it. Either reading leaves a defect: the code and the javadoc disagree. Verdict: real, low impact.

Two options. The < 0 check matches the only written contract and was validated with gradle in a scratch worktree at 645d4fe14a20; making -1 the documented sentinel and rejecting other negatives up front is the alternative a maintainer may prefer (not executed). Either way, do not fix only the capacity line (for example Math.max(0, Math.min(maxPassages, 10)) at :112): the loop while (passages.size() < maxPassages) (:115) then never runs for a negative count, so -2 would silently return null, the documented 0 behaviour, still contradicting the javadoc (code reading). A natural combination: the < 0 check plus one sentence of javadoc on Builder#withMaxNoHighlightPassages that repeats the getter's contract.

In FieldHighlighter.highlightFieldForDoc, compare with < 0 instead of == -1.

        passages =
            getSummaryPassagesNoHighlight(
                maxNoHighlightPassages < 0 ? maxPassages : maxNoHighlightPassages);

Trade-offs

• Stock FieldHighlighter: -1 unchanged; every other negative value now gives the first maxPassages sentences, as the javadoc says; 0 and positive values unchanged. No API change.
• It validates nothing, so a subclass override of the getter returning a negative value is treated as the default too, which is what the javadoc promises.
• Custom extensions are the one thing to consider: the mapping happens before the protected getSummaryPassagesNoHighlight(int) hook, so a custom FieldHighlighter that overrides that hook and relies on receiving a raw negative value other than -1 would now get maxPassages (upstream's extensibility test subclasses FieldHighlighter from outside the package, TestUnifiedHighlighterExtensibility.java:167-194, :259-284; code reading).
• It does not cover a negative maxPassages request argument, which has no documented range and is not claimed here: with the default -1 such a value reaches the same line 112, with or without the fix (code reading).

What the checks validated

• Gradle, own scratch worktree at 645d4fe14a20, JDK 25.0.3, -Ptests.seed=DEADBEEF (2026-10-30): without the fix the minimal test fails (Illegal Capacity: -2); with it, :lucene:highlighter:test --tests 'org.apache.lucene.search.uhighlight.*' passes 471 of 471 tests in 14 suites (the package's 470 upstream tests plus the minimal test), and the whole :lucene:highlighter:test passes 723 of 723 tests in 35 suites, 0 failures, 0 errors.
• Earlier shadow runs on ea57360912ed: the finder's test, an independent reproducer's 7 tests, the other verifiers' tests and the audit's test pass with it. The diagram probe on 645d4fe14a20 with the fix returns First sentence. for -2, -3, Integer.MIN_VALUE, the deprecated setter and the -5 override, and both snippets for the two-field call.

Change the getter javadoc to say -1 (the default), and throw IllegalArgumentException with a message for values below -1 in Builder#withMaxNoHighlightPassages and setMaxNoHighlightPassages, as withMaxLength does. Not executed.

Trade-offs

A clear, early error, consistent with withMaxLength. But it narrows the documented contract, and a subclass that overrides getMaxNoHighlightPassages bypasses the setter check, so FieldHighlighter.java:93 (or getFieldHighlighter) would need a check too.

Method: bounded-exhaustive translation validation (the hunt's semi-formal tier), in a hunt unit on the UnifiedHighlighter's passage layer, run on the stock main jars at ea57360912ed.

• A reference implementation of passage splitting and the default summary was written from the javadoc (for the summary: N = maxPassages when maxNoHighlightPassages < 0), plus the oracle "no exception on legal input".
• The harness compared the real jar with it on every text of up to 5 code points over the alphabet {a, b, space, '.', U+1D400, '<', '&'}, 7 break iterators, maxPassages 1 to 3 and maxNoHighlightPassages -2 to 2.
• The first signal was code reading: the finder noticed the == -1 check while writing the reference. The exhaustive run witnessed it: every no-match call with -2 threw Illegal Capacity: -2 (604,380 per iterator). A hand-written public-API JUnit confirmed it, later reduced to the single test shown here.