DirectSpellChecker: numSug * maxInspections overflows int, so setMaxInspections(Integer.MAX_VALUE) with an even numSug returns no suggestions or throws NullPointerException

DirectSpellChecker.suggestSimilar sizes its candidate search with int inspections = numSug * maxInspections; (DirectSpellChecker.java:359 on main 645d4fe14a20), and setMaxInspections stores any int (:145-147). With setMaxInspections(Integer.MAX_VALUE), the largest accepted value (no upper bound is documented), the product is -numSug for every even numSug and 2^31 - numSug for odd ones. A negative budget makes the one-edit pass treat its empty queue as full and dereference PriorityQueue.peek() == null (NullPointerException at :435) when the word has a one-edit neighbour, and makes the two-edit pass never run (:363, 0 < -2 is false) when it has none, so the call silently returns an empty array. On a one-word index the same settings give [lucene] for numSug 1 and 3 and [] for numSug 2. 2^30 and Integer.MAX_VALUE - 1 wrap too; at the default 5 only absurd counts do, from numSug 429,496,730 on (numSug 858,993,460 returns 4 of 10 suggestions). Every release that has the class is affected, from 4.0.0-ALPHA (2012) to 10.6.0 (run as its release candidate) and main. Computing the product in long and capping it at Integer.MAX_VALUE fixes it.

• numSug: the count argument of suggestSimilar, "the maximum number of suggested words" (DirectSpellChecker.java:314).
• maxInspections: "the maximum number of top-N inspections (default: 5) per suggestion" (:141-143). setMaxInspections stores the value as given (:145-147); setMaxEdits, by contrast, rejects values outside 1..2 (:114-117).
• Budget: int inspections = numSug * maxInspections; (:359). It is passed as the numSug argument of the protected per-pass method (:410-479), which keeps the best candidates in a java.util.PriorityQueue (:426).

1. The product wraps. Integer.MAX_VALUE is 2^31 - 1, so numSug * maxInspections is numSug * 2^31 - numSug; modulo 2^32 that is -numSug for even numSug and 2^31 - numSug for odd numSug. 2 * 2,147,483,647 = 4,294,967,294 becomes -2.
2. Pass 1, one edit away (:362). For each candidate, :435 first skips uncompetitive hits: if (stQueue.size() >= numSug && score <= stQueue.peek().boost). With numSug = -2, 0 >= -2 is true on the empty queue, peek() is null, and reading .boost throws NullPointerException.
3. Pass 2, two edits away (:363): if (maxEdits > 1 && terms.size() < inspections). If pass 1 found nothing (so no NPE), 0 < -2 is false, pass 2 never runs, and :372-392 return an empty array.
4. Small odd counts work. For every odd numSug the budget 2^31 - numSug is positive, and up to 2^30 it is at least numSug, so the same checker gives the right answer for 1, 3, 5 suggestions and fails for 2, 4, 6. Above 2^30 the odd budget is smaller than numSug: numSug Integer.MAX_VALUE gets a budget of 1 and returns 1 of 10 suggestions.

• One indexed word lucene, word luxeny (two edits away), setMaxInspections(Integer.MAX_VALUE): numSug 1 returns [lucene], numSug 2 returns [], numSug 3 returns [lucene]. With setMaxInspections(1000), numSug 2 returns [lucene].
• Index lucene, lucent, lucerne, word lucenx, numSug 2: setMaxInspections(1000) returns [lucene, lucent]; Integer.MAX_VALUE throws NullPointerException: Cannot read field "boost" because the return value of "java.util.PriorityQueue.peek()" is null at DirectSpellChecker.java:435.
• Other "unlimited" values: 2^30 fails for every count except 1, 5, 9, ... (2 gives -2^31, 3 gives -2^30, 4 gives 0; 5 wraps to 2^30 itself); Integer.MAX_VALUE - 1 gives -2 * numSug for even counts. At the default 5, numSug 429,496,730 to 858,993,459 give a negative budget, and numSug 858,993,460 gives a budget of 4: 4 of 10 suggestions, no error. Larger counts keep alternating between negative and wrapped positive budgets (858,993,461 gives 9).

• Who is exposed. Code that calls setMaxInspections with a sentinel-sized value meaning "inspect everything" and requests an even number of suggestions. With 2^30 every count except 1, 5, 9, ... fails (n * 2^30 mod 2^32 is (n mod 4) * 2^30).
• Opt-in. It needs a non-default setMaxInspections value; nothing else non-default is needed: default codec, default IndexWriterConfig, one indexed term suffices, single thread, deterministic (the empty leg uses the default two-edit pass, maxEdits 2).
• Effect. A word for which the one-edit pass finds a candidate gets a NullPointerException from suggestSimilar. A word whose only neighbours are two edits away gets an empty list with no error, which looks exactly like "no suggestion exists". How often each case occurs in real traffic was not measured. Because small odd counts work, a developer who tests with 1, 3 or 5 suggestions sees nothing wrong. Nothing persists; the index and searches are not affected.
• Default setting. With maxInspections 5 only counts of 429,496,730 or more wrap, far beyond any real request; the javadoc itself says "typically a low value for numSug will work very well" (:310-311).
• How likely: rare. No report of the NPE or the wrong results from this trigger since 4.0 (2012); the only public trace of the overflow is a downstream source comment (see Prior reports). The author's own example value is 5. Downstream servers that forward an inspection limit are covered in the note below; their reach was read, not executed.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<[lucene]> but was:<[]>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:120)
       org.junit.Assert.assertEquals(Assert.java:146)
       org.apache.lucene.search.spell.TestDirectSpellCheckerMaxInspections.testMaxInspectionsMaxValue(TestDirectSpellCheckerMaxInspections.java:45)

• Contract. setMaxInspections (DirectSpellChecker.java:141-143): "Set the maximum number of top-N inspections (default: 5) per suggestion. Increasing this number can improve the accuracy of results, at the cost of performance." No upper bound and no validation (:145-147). suggestSimilar (:314, :318): "@param numSug the maximum number of suggested words", "@return sorted list of the suggested words according to the comparator".
• The class tells users to raise it. setDistance (:281-284): "If you use a different metric than the default, you might want to consider increasing {@link #setMaxInspections(int)} to draw more candidates for your metric to rank."
• Integer.MAX_VALUE means "no limit" in this class. maxQueryLength defaults to it (:82; LUCENE-9102, #10144).
• The parity oracle needs no promise about maxInspections. It compares two counts on the same settings: asking for up to 2 suggestions cannot rightly lose the one that a request for 1 finds.
• History. The product, the setter, the pass-2 guard and the peek() check all come from the commit that created the class (5190ea52329, LUCENE-2507, 2010); no later commit changed the product or the guard. No test, CHANGES or MIGRATE entry bounds maxInspections, and no test calls setMaxInspections.
• Precedent. LUCENE-2119 (#3195, by mikemccand, resolved 2010-06-01): Integer.MAX_VALUE as the hit count of search(Query, int) wrapped in int and threw. The report itself calls it "a nonsense value to pass in" and says "This trips users up fairly often"; it was fixed rather than rejected (the priority queue no longer adds 1 to Integer.MAX_VALUE, and search caps the count at maxDoc()).

The strongest case for "works as designed" (the intended-behaviour checker and the reviews by another model family): the class is @lucene.experimental (:48); its author described the parameter as "maxInspections (example: 5), the existing spellchecker uses a hardcoded 10 here. A lower value can work well here" (rmuir on LUCENE-2507 / #3581, 2010-10-01); "can improve" is no promise that results improve monotonically; and open #9195 already asks for parameter checks, so a maintainer could answer "reject silly values".

Why it fails: experimental status does not license wrong results; the author gave an example, not a limit, and no doc, test or check sets one; the parity oracle compares two counts on the same settings and needs no monotonicity in maxInspections; range checks do not reject two positive values, the default-setting leg overflows with maxInspections = 5, and rejecting Integer.MAX_VALUE would break the odd counts that work today. What remains is an impact and likelihood argument (sentinel values only), which the Low priority already reflects. Verdict: a defect.

One fix was built and validated with gradle; the alternatives were not built.

DirectSpellChecker.java:359, one file, +2/-1:

    // numSug * maxInspections can overflow int (e.g. maxInspections = Integer.MAX_VALUE)
    int inspections = (int) Math.min((long) numSug * maxInspections, Integer.MAX_VALUE);

Trade-offs

• Behaviour is unchanged whenever the product fits in an int (a Z3 proof over positive inputs, in the model's candidate-count abstraction: the value equals today's when there is no overflow, is >= numSug and >= 1 otherwise, and the long product cannot overflow).
• When it does not fit, the budget is Integer.MAX_VALUE, close to the 2^31 - numSug that small odd counts already get today: the per-pass method then keeps every candidate within the edit distance until its queue holds Integer.MAX_VALUE entries, and pass 2 runs. java.util.PriorityQueue is not pre-sized, so nothing large is allocated up front, but the queue grows with every candidate kept: on a large index with many terms within two edits the call can do much more work and hold much more memory than today's wrong answer. Not measured.
• Not covered: non-positive numSug or maxInspections, the separate, open #9195 / SOLR-11858 request for parameter checks, which is complementary. The fix leaves them as they are today: the :435 NPE when the one-edit pass finds a candidate, an empty array when it finds none, or a NegativeArraySizeException at :388 for a negative numSug (executed on main and with the fix: the same outcomes).

What the checks validated

• Scratch worktree of main 645d4fe14a20, gradle: the new test fails on the stock tree and passes with the fix, with assertions on and off. The whole lucene/suggest module passes with assertions on and off: 32 suites (31 upstream plus the new test), 237 tests, 7 skipped, 0 failures; search.spell 9 suites, 32 tests, including TestDirectSpellChecker 6 of 6. :lucene:suggest:check -x test (google-java-format, ecjLint, forbiddenApis) passes.
• Standalone runner with the fixed class: the new test, the finder's two tests (the NPE and the empty leg) and the independent reproducer's three tests (including the default-5 leg with numSug 858,993,460) pass. The same one-line fix makes 4.0.0-ALPHA pass.

Reject numSug < 1 and maxInspections < 1 with IllegalArgumentException.

Trade-offs

Does not fix this bug: both values are positive here. Worth adding alongside the saturation. Not built.

Throw ArithmeticException on overflow.

Trade-offs

Loud instead of silent, but it rejects the natural "inspect everything" setting that works for odd counts today. Not built.

Clamp maxInspections to some maximum.

Trade-offs

Any cap is arbitrary, and a huge count at the default setting still overflows. Not built.

Change the protected suggestSimilar(Term, int numSug, IndexReader, int, int, float, CharsRefBuilder).

Trade-offs

The method is protected and overridable, so the signature change breaks subclasses. Not recommended. (The open draft #16847, long doc ids, does change another parameter of this method, int docfreq to long.)

Method: non-formal first signal, semi-formal for the empty leg (the hunt's numeric-limits hunt unit, 2026-10-28, main a9779ef3c193).

• Lead. A planning probe that tries extreme values of numeric parameters on the stock jars failed 7 of 11 checks, including the NPE for setMaxInspections(Integer.MAX_VALUE) with numSug 2 and the truncation to 4 of 10 at the default with numSug 858,993,460.
• Z3 model. The finder modelled the budget arithmetic and the result size as 32-bit bit-vectors (18 checks, 0 unexpected). T1 proves the budget is <= 0 exactly when numSug is even (with Integer.MAX_VALUE); witness W2, found while modelling the pass-2 guard at :363, is the silently empty leg the probe did not have; F1-F4 prove the saturating fix.
• Model-based test. 200 random indexes, numSug 1 to 8 and 11 maxInspections values on the stock jar: 13,950 of 44,720 checks fail, none without int overflow, and the model predicts all 98,384 observed outcomes. With the fix, 0 fail.