SpellChecker.suggestSimilar computes 10 * numSug in int, so numSug = Integer.MAX_VALUE throws "numHits must be > 0" instead of returning the suggestions

SpellChecker.suggestSimilar(word, numSug), Lucene's classic n-gram spell checker, fetches ten times as many candidate words from its spell index as the suggestions requested and computes that budget as int maxHits = 10 * numSug. For numSug = Integer.MAX_VALUE ("all suggestions") the product wraps to -10; IndexSearcher.search(query, n) caps n with min(n, max(1, maxDoc)), which keeps the negative value, and TopScoreDocCollectorManager throws IllegalArgumentException: numHits must be > 0; please use TotalHitCountCollectorManager if you just need the total hit count, naming a parameter the caller never passed. The javadoc sets no upper bound on numSug and nothing validates it, while the search below is tested to accept Integer.MAX_VALUE. Every count whose product wraps to zero or below fails (1,073,741,824 values in five blocks, the first at 214,748,365); where it wraps to a small positive number the call silently returns fewer suggestions (numSug = 429,496,730: 4 of 9). A second line sizes the result queue by numSug, so the fix has two lines: compute the budget in long and saturate it, and size the queue by min(numSug, hits.length). Every release from 1.9 to 10.6.0 and main is affected; it is not a regression (Integer.MAX_VALUE never worked, only the exception changed), no index data or search results are affected, and ordinary counts up to 214,748,364 work.

• Contract. SpellChecker.java:224-241: "you should set this value to <b>at least</b> 5 for a good suggestion" (:232-233) and "@param numSug the number of suggested words" (:236; the same on :258, :293); :303-305 return "the sorted list of the suggest words". No upper bound, no @throws for a large count; the overloads :242, :266, :275 reach :307, which never checks numSug.
• The product. :361 int maxHits = 10 * numSug;: 10 * 2147483647 = -10, 10 * 214748365 = -2147483646, 10 * 429496730 = 4.
• The search. :364 indexSearcher.search(query.build(), maxHits). IndexSearcher.search (IndexSearcher.java:623-625) calls searchAfter, which caps with Math.min(numHits, Math.max(1, reader.maxDoc())) (:588, :597): a negative value passes the cap, and new TopScoreDocCollectorManager(...) (:598-599) throws for numHits <= 0 (TopScoreDocCollectorManager.java:62-64).
• The queue. :366 new SuggestWordQueue(numSug, comparator), a PriorityQueue that "pre-allocates an array of length maxSize+1" (PriorityQueue.java:34-35, @lucene.internal) and refuses maxSize >= 2147483631 (:121-124), sized by numSug whatever the hit count.
• The loop. :369 int stop = Math.min(hits.length, maxHits); inspects at most stop hits, so a small positive wrapped budget looks at only that many candidates; the result is visibly short only when more viable candidates exist than that budget.
• Scope. The 2-argument overload always reaches :361. The 6-argument method can return earlier: with a user index and field in SUGGEST_WHEN_NOT_IN_INDEX mode, a word present in that index returns [word] at :332-334 before the product is computed.
• Both lines matter. With only :361 fixed, Integer.MAX_VALUE fails at :366 with IllegalArgumentException: maxSize must be >= 0 and < 2147483631; got: 2147483647, and 214,748,365 ends in OutOfMemoryError at -Xmx512m.
• The layer below. TestIndexSearcher.java:78-79 // should not throw exception / testHugeN() calls searcher.search(query, Integer.MAX_VALUE) (:101).

Below the threshold each call allocates in proportion to numSug, because the queue has numSug + 1 slots whatever the hit count. Measured for the whole call (always 7 suggestions on a 10-word dictionary; a9779ef3c193, same SpellChecker.java): about 0.2 MiB at 10 and at 1,000 (of which the queue is about 4 KB at 1,000), and 381.7 MiB at 10^8, almost all of it the queue. The wrap blocks with a product of zero or below are 214,748,365-429,496,729, 644,245,095-858,993,459, 1,073,741,824-1,288,490,188, 1,503,238,554-1,717,986,918 and 1,932,735,284-2,147,483,647.

• Who is hit. Code that passes a huge numSug to any suggestSimilar overload. No setting is needed, and the dictionary size does not matter: a one-word dictionary fails.
• What goes wrong. For 1,073,741,824 counts the call throws an exception that names numHits and recommends TotalHitCountCollectorManager, neither of which the caller used. Where the product wraps to a small positive budget, the call can return fewer suggestions with no error; that needs a count of at least 429,496,730 and a queue of about 1.6 GiB first. Below the threshold results are right, but memory follows the count (381.7 MiB at 10^8).
• Not a regression. Integer.MAX_VALUE has never worked: NegativeArraySizeException in 1.9 to 2.9.1, "nDocs must be > 0" in 2.9.2 to 3.0.3, "numHits must be > 0" since 3.1.
• Workaround. Cap the count before calling, for example at the number of words in the spell index; any count up to 214,748,364 works, given a heap large enough for the numSug-sized queue (about 0.8 GiB at 214,748,364).
• How likely. Rare: usual counts (the javadoc asks for "at least 5"; upstream tests use 1 to 10) never come near the threshold, and the recorded searches found no earlier report.
• Downstream (read, not executed). By default, Solr's index- and file-based spell checkers pass max(spellcheck.count, 5) to suggestSimilar (with a non-zero alternativeTermCount they pass that count instead for a word that is in the index), and Solr reads spellcheck.count with no upper bound; Lucene.NET's port has the same two lines (SpellChecker.cs:364, :369).

Copy the test into lucene/suggest/src/test/org/apache/lucene/search/spell/ of a Lucene checkout and run the command below. It sits in that package only because the module's tests live there; it uses no package-private member. The result does not depend on the seed (newDirectory() is the only randomised part).

Lucene's build picks assertions per seed (about 75% of seeds run with them; DEADBEEF runs without), so add -Ptests.asserts=true or -Ptests.asserts=false to choose; it fails both ways. The catch only turns the exception into an assertion failure that states expected vs actual; pass e as the cause if you want the stack trace in the failure. The test passes the module's format check as is.

cp $REPRO/TestSpellCheckerNumSugOverflow.java $LUCENE/lucene/suggest/src/test/org/apache/lucene/search/spell/
cd $LUCENE && ./gradlew :lucene:suggest:test --tests org.apache.lucene.search.spell.TestSpellCheckerNumSugOverflow -Ptests.seed=DEADBEEF
# add -Ptests.asserts=true or -Ptests.asserts=false to choose the assertion mode; it fails both ways

# gradle, fresh worktree at main 645d4fe14a20, -Ptests.seed=DEADBEEF -Ptests.asserts=true (module prefixes trimmed)
TestSpellCheckerNumSugOverflow > testNumSugIntegerMaxValue FAILED
    java.lang.AssertionError: expected [lucene] for numSug = Integer.MAX_VALUE; actual: numHits must be > 0; please use TotalHitCountCollectorManager if you just need the total hit count
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:599EE7562846F7E3]:0)
        at junit@4.13.2/org.junit.Assert.fail(Assert.java:89)
        at org.apache.lucene.search.spell.TestSpellCheckerNumSugOverflow.testNumSugIntegerMaxValue(TestSpellCheckerNumSugOverflow.java:34)
1 test completed, 1 failed
# the same with -Ptests.asserts=false and with the seed's default

# the throwing frames (a probe that keeps the exception; main 645d4fe14a20, -ea and -da)
java.lang.IllegalArgumentException: numHits must be > 0; please use TotalHitCountCollectorManager if you just need the total hit count
    at org.apache.lucene.search.TopScoreDocCollectorManager.<init>(TopScoreDocCollectorManager.java:63)
    at org.apache.lucene.search.IndexSearcher.searchAfter(IndexSearcher.java:598)
    at org.apache.lucene.search.IndexSearcher.search(IndexSearcher.java:624)
    at org.apache.lucene.search.spell.SpellChecker.suggestSimilar(SpellChecker.java:364)
    at org.apache.lucene.search.spell.SpellChecker.suggestSimilar(SpellChecker.java:278)
    at org.apache.lucene.search.spell.SpellChecker.suggestSimilar(SpellChecker.java:243)

# standalone runner, the minimal test (tests_run=1 failures=1 each)
main 645d4fe14a20, 10.6.0, 10.5.2   -ea and -da, seed DEADBEEF   the same AssertionError

• The exception is an overflow artifact, not a check. It fires at 214,748,365, the point where 10 * numSug passes Integer.MAX_VALUE; no comment, test, CHANGES entry or commit chooses that threshold. The pre-allocation note sits on the @lucene.internal PriorityQueue (PriorityQueue.java:34-35, :39), which the suggestSimilar javadoc does not reference. Nothing documents Integer.MAX_VALUE as an "all suggestions" value either: it is a request for more suggestions than exist, which the contract does not forbid.
• LUCENE-2119 (#3195, reported by Michael McCandless, type:bug, fixed in 2.9.3, 3.0.2 and 3.1): "If you pass Integer.MAX_VALUE as 2nd param to search(Query, int) you hit unexpected NegativeArraySizeException"; "This trips users up fairly often because they assume our PQ doesn't statically pre-allocate (a reasonable assumption...)"; "in IndexSearcher, if that n is ever > maxDoc(), set it to maxDoc()". That cap is IndexSearcher.java:597. This is context for the search's own contract, not proof that SpellChecker promises the same.
• Precedent in this file. LUCENE-10533 (#11569, Kevin Risden, type:bug, fixed in 9.2), a missing bounds check in SpellChecker.formGrams reached from Solr: "There is an argument that the caller should not be invalid, but a simple bounds check would prevent this in Lucene".
• The sibling spell checkers are no counter-example. WordBreakSpellChecker returns an empty result below 1 and caps its initial queue capacity at 10 (WordBreakSpellChecker.java:81-83, :91). DirectSpellChecker is no evidence that large counts are supported: it returns its full result for Integer.MAX_VALUE only because its own int product numSug * maxInspections (DirectSpellChecker.java:359, default 5 at :67) happens to wrap to the positive 2,147,483,643; with default settings 500,000,000 throws NullPointerException there and 858,993,460 returns 4 of 10 (executed first-signal probe), which is the sibling LFV-986.
• History. The factor 10 is a recall heuristic (LUCENE-786, Karl Wettin: "I suppose that number (10) was something the original author came up with when testing"); :361 came from the mechanical LUCENE-1856 "Remove Hits" migration. Nothing discusses bounds.

The strongest case for "works as designed" (built by an intended-behaviour devil's advocate; reading-only reviewers from another model family, OpenAI GPT-5.6, rated it "moderate" and "weak"): a spell checker asked for hundreds of millions of suggestions is an odd request, and the javadoc's only guidance is small ("at least 5"; DirectSpellChecker adds "typically a low value for numSug will work very well"); PriorityQueue documents its up-front allocation, and SuggestWordQueue(int size, ...) takes "the size of the queue", so sizing it by numSug is designed use; in LUCENE-2119 the reporter called n = Integer.MAX_VALUE "a nonsense value to pass in, since our PQ impl allocates the array up front"; Integer.MAX_VALUE has never worked in any SpellChecker release, and a reviewer argued that "a clear validation exception would still be preferable".

Why it fails: LUCENE-2119 was still fixed as a bug, in the very search SpellChecker calls, and testHugeN keeps that contract; the request is feasible (with the fix every count, Integer.MAX_VALUE included, returns the full result at -Xmx512m); today's behaviour is not a clear validation exception but an overflow artifact about another parameter, plus a silent short result in other blocks. The argument does bear on priority (Low) and on the likely reply: a maintainer may prefer a bound check (option B) over saturation, and either resolves the bug.

Three options; A was validated with gradle in a fresh scratch worktree at 645d4fe14a20, B and C were not executed. A maintainer may prefer B, a clear bound check; either resolves the bug. Separate choice: numSug = 0 also throws "numHits must be > 0" today (not claimed), while WordBreakSpellChecker returns an empty result for counts below 1; one change could handle both ends.

In SpellChecker.suggestSimilar, :361 becomes int maxHits = (int) Math.min(10L * numSug, Integer.MAX_VALUE); and :366 becomes new SuggestWordQueue(Math.min(numSug, hits.length), comparator). +4/-2 lines in one file, two of them comments.

// saturate: 10 * numSug overflows int for numSug >= 214748365 (e.g. Integer.MAX_VALUE)
int maxHits = (int) Math.min(10L * numSug, Integer.MAX_VALUE); // was: 10 * numSug

ScoreDoc[] hits = indexSearcher.search(query.build(), maxHits).scoreDocs;
// size the queue by what the search can return, not by numSug
SuggestWordQueue sugQueue =
    new SuggestWordQueue(Math.min(numSug, hits.length), comparator); // was: numSug

Trade-offs

• No change in results for counts that do not overflow. Up to 214,748,364 the product is exact, and the queue size is numSug whenever numSug <= hits.length. When numSug > hits.length, a queue of hits.length slots holds every inspected hit (at most stop <= hits.length inserts, :369), as the larger queue did; the "queue full" accuracy raise (:396-399) cannot fire in either version, because the queue never reaches numSug entries.
• Positive-wrap counts change on purpose. Today they can return a silently short result (429,496,730: 4 of 9); with the fix they return the full 9.
• Allocations are bounded by the spell index, not by the count. With the saturated budget IndexSearcher caps n at maxDoc, the path testHugeN covers, and the queue gets hits.length <= maxDoc slots (a large spell index still means large allocations).
• For numSug <= 0 the fix computes exactly today's maxHits and queue size, so behaviour there does not change.
• Both lines are needed: with only the first, Integer.MAX_VALUE fails in PriorityQueue ("maxSize must be >= 0 and < 2147483631") and 214,748,365 runs out of memory at -Xmx512m.
• The minimal test, as the regression test, covers only Integer.MAX_VALUE; the positive-wrap leg was checked only with the tie-breaker's probe, and counts <= 0 are not tested.

What the checks validated

• Fresh scratch worktree at 645d4fe14a20, JDK 25.0.3, gradle with -Ptests.seed=DEADBEEF (2026-10-30): without the fix the minimal test fails with the seed's default, -Ptests.asserts=true and -Ptests.asserts=false; git apply of the diff succeeds; with it, :lucene:suggest:checkGoogleJavaFormat and the minimal test pass (assertions on and off).
• --tests 'org.apache.lucene.search.spell.*': 9 suites, 32 tests, 0 failures, including TestSpellChecker (6), TestDirectSpellChecker (6), TestWordBreakSpellChecker (5) and TestLuceneDictionary (6). The whole :lucene:suggest:test: 32 suites, 237 tests, 7 skipped, 0 failures.
• Earlier, with the same fix shadowed onto the main jars: a 5-test probe passes at -Xmx512m (Integer.MAX_VALUE, 214,748,365, 214,748,364 and 429,496,730 all return the 9 suggestions; -ea and -da), and upstream TestSpellChecker passed 6 of 6.

For example if (numSug < 1 || numSug > Integer.MAX_VALUE / 10) throw new IllegalArgumentException(...) at the top of the 6-argument suggestSimilar. Not executed.

Trade-offs

Replaces the misleading exception and the silent short result with a clear error and needs no change at :366, but keeps "all suggestions" an error (unlike the search below, which accepts Integer.MAX_VALUE) and keeps the numSug-sized pre-allocation for large legal counts (381.7 MiB at 10^8).

The spell index holds one document per indexed word (SpellChecker.java:534-535; indexDictionary skips words shorter than 3 characters and words already in the spell index, :521-530), so at most maxDoc suggestions exist: clamp numSug to it, then compute the budget in long. Not executed.

Trade-offs

Same effect as A in one place, but it changes the numSug that the "queue full" check (:396) compares against, so it needs the same reasoning about unchanged results.

Method: executed differential testing, then SMT modelling (the hunt's non-formal tier: the first signal was an executed probe, not a model).

• First signal. In a round on numeric limits of public API arguments, a planning probe ran SpellChecker.suggestSimilar on a 10-word dictionary with Integer.MAX_VALUE, 214,748,365 and 10^8 on the stock jars of main a9779ef3c193, 10.5.2, 9.12.3 and the 10.6 release candidate (2026-10-28): the first two threw "numHits must be > 0", the third returned after a 381 MiB allocation.
• Hunt. A finder wrote a public-API JUnit (2 of 2 fail with -ea and -da), a Z3 bit-vector model of the budget (properties S1-S4, 18 checks, 0 unexpected) and an exact enumeration of the wrap blocks, located both lines by reading the code, and wrote and checked the two-line fix (and showed that a one-line fix only moves the failure). Found 2026-10-28.
• Checks. An independent reproducer executed the modelled silent leg (4 of 7 suggestions); an intended-behaviour devil's advocate, an adjudication, a credibility audit, a current-main re-check and a tie-breaker confirmed it; the single test shown here is the audited reduction.