NGramTokenizer and EdgeNGramTokenizer accept maxGram = Integer.MAX_VALUE, but their buffer sizing overflows, so the first text of 17 or more chars throws

NGramTokenizer and EdgeNGramTokenizer (its subclass) accept maxGram = Integer.MAX_VALUE: init checks only minGram >= 1 and minGram <= maxGram. It then sizes the read buffer with CharacterUtils.newCharacterBuffer(2 * maxGram + 1024) and calls termAtt.resizeBuffer(2 * maxGram), both in int. For Integer.MAX_VALUE, 2 * maxGram wraps to -2: the read buffer gets 1022 chars, and resizeBuffer(-2) is a no-op, so the term buffer keeps its default size, 16 chars on a 64-bit JVM. With minGram = 1, texts of up to 16 chars tokenize correctly; the first text of 17 chars throws ArrayIndexOutOfBoundsException: Index 16 out of bounds for length 16 from incrementToken, and from 1022 chars (text without supplementary characters) an IllegalArgumentException from CharacterUtils.fill. The constructors, CustomAnalyzer and the nGram / edgeNGram factories (maxGramSize=2147483647) all reach it, at index time and at query time, while the n-gram token filters accept the same value and work. Introduced in 4.4.0 by LUCENE-5042 (2013); every release from 4.4.0 to 10.6.0 and main is affected. Opt-in and rare; documents are rejected one by one and nothing is corrupted.

1. Accepted. NGramTokenizer.init throws only for minGram < 1 and minGram > maxGram (NGramTokenizer.java:118-124). EdgeNGramTokenizer extends NGramTokenizer (EdgeNGramTokenizer.java:30) and passes maxGram through; both factories read maxGramSize with getInt and pass it on unchecked (EdgeNGramTokenizerFactory.java:48-49, NGramTokenizerFactory.java:50-51).
2. Read buffer wraps. charBuffer = CharacterUtils.newCharacterBuffer(2 * maxGram + 1024) with the comment "2 * maxGram in case all code points require 2 chars and + 1024 for buffering to not keep polling the Reader" (:128-132). 2 * 2147483647 is -2 in int, so the size is 1022, which passes the only check, bufferSize < 2 (CharacterUtils.java:39-43). The code-point buffer gets the same length (:133).
3. Term buffer never grows. "// Make the term att large enough", termAtt.resizeBuffer(2 * maxGram) (:134-135), i.e. resizeBuffer(-2). CharTermAttributeImpl.resizeBuffer grows only if (termBuffer.length < newSize) (CharTermAttributeImpl.java:57-58), so the buffer keeps its initial ArrayUtil.oversize(10, Character.BYTES) chars (:30-32): 16 on a 64-bit JVM (read back after construction in an executed probe), 14 on a 32-bit one (ArrayUtil.java:174-203).
4. Overflow. gramSize > maxGram (:162) is never true, so grams grow with the text. CharacterUtils.toChars(buffer, bufferStart, gramSize, termAtt.buffer(), 0) (:184) writes the 17th char of the 17-char prefix to index 16 of the 16-char buffer.
5. From 1022 chars (text without supplementary characters). The compaction test at :146 is always true, so every call refills. After a first fill of 1022 one-char code points, buffer.length - bufferEnd is 0, and CharacterUtils.fill (:154) rejects it: "numChars must be >= 2 and <= the buffer size" (CharacterUtils.java:177-178).

Text of supplementary characters fails as soon as a gram passes 16 chars (Index 17 out of bounds for length 16, for example 9 emoji = 18 chars), also from 1022 chars, because its first fill holds only 511 code points.

Not part of the claim (contrived): with a large minGram (1023 or more, or 512 or more for text of supplementary characters) on a text longer than the read buffer, incrementToken reaches assert exhausted; return false (:163-165) before any token, so the stream is silently empty with assertions off (NGramTokenizer(1023, Integer.MAX_VALUE) on 1100 a: 0 tokens instead of 3081) and throws AssertionError with them on. The fix below rejects these settings too.

• Who is hit. Users of the two tokenizers with maxGram = Integer.MAX_VALUE (or one of the 510 values just below it), for example "all prefixes" with EdgeNGramTokenizer. All entry points reach it: the constructors, CustomAnalyzer with edgeNGram / nGram, the factories' create(), and a schema with maxGramSize=2147483647.
• Default vs opt-in. Opt-in: the n-gram tokenizers are optional analysis-common components with defaults maxGram = 2 (NGramTokenizer) and 1 (EdgeNGramTokenizer).
• What goes wrong. The failure is deferred and depends on the data: a quick test with short strings passes, then every text of 17 chars or more throws from incrementToken. At index time addDocument throws for that document, the writer stays open, later documents index and CheckIndex is clean; at query time QueryBuilder throws the same exception. With minGram = 1 no output is silently wrong; only a contrived large-minGram setting ends a stream early (see the full explanation above).
• Harder to trace in a long-running JVM. With default JVM flags, after repeated failures the JVM's fast-throw optimisation drops the message and stack: later failures show as ArrayIndexOutOfBoundsException: null with no Lucene frame.
• Scale. None: 17 chars. Deterministic, single-threaded, assertions on or off.
• Workaround. A finite maxGram (the longest text you expect), or EdgeNGramTokenFilter / NGramTokenFilter, which accept Integer.MAX_VALUE and work.
• How likely. Rare. The idiom exists: an old Solr geohash plugin builds EdgeNGramTokenizer(input, Side.FRONT, 1, Integer.MAX_VALUE) on the pre-4.4 API, and its geohashes are 22 chars by default, so on 4.4.0 or later the same idiom would fail on every value. But the failure is loud on the first long value and the documented public searches found no report of it since 4.4.0 (2013).

Copy the test into lucene/analysis/common/src/test/org/apache/lucene/analysis/ngram/ of a Lucene checkout and run it with gradle (command below). 17 chars is the smallest failing input: 16 chars still work. With the fix it passes unchanged, so it doubles as the regression test.

The test logic has no random branch; it failed under every recorded seed, with assertions on and off. NGramTokenizer(1, Integer.MAX_VALUE), both factories, CustomAnalyzer, IndexWriter.addDocument and QueryBuilder fail the same way (executed with independent main() probes); they are left out of the test on purpose.

Executed: gradle on a clean 645d4fe14a20 (fails); the standalone runner on the stock main jars with -ea and -da and several seeds, and on the 10.6.0 and 10.5.2 release jars with -ea and -da (fails).

cp $REPRO/TestEdgeNGramTokenizerMaxGramIntegerMaxValue.java $LUCENE/lucene/analysis/common/src/test/org/apache/lucene/analysis/ngram/
cd $LUCENE && ./gradlew :lucene:analysis:common:test --tests org.apache.lucene.analysis.ngram.TestEdgeNGramTokenizerMaxGramIntegerMaxValue -Ptests.seed=DEADBEEF

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF (module prefixes and 5 test-framework frames trimmed)
TestEdgeNGramTokenizerMaxGramIntegerMaxValue > testSeventeenCharText FAILED
    java.lang.AssertionError: expected the 17 prefixes of abcdefghijklmnopq or an IllegalArgumentException, got java.lang.ArrayIndexOutOfBoundsException: Index 16 out of bounds for length 16
        at org.apache.lucene.analysis.ngram.TestEdgeNGramTokenizerMaxGramIntegerMaxValue.testSeventeenCharText(TestEdgeNGramTokenizerMaxGramIntegerMaxValue.java:41)

        Caused by:
        java.lang.ArrayIndexOutOfBoundsException: Index 16 out of bounds for length 16
            at java.base/java.lang.Character.toChars(Character.java:9873)
            at org.apache.lucene.analysis.CharacterUtils.toChars(CharacterUtils.java:145)
            at org.apache.lucene.analysis.ngram.NGramTokenizer.incrementToken(NGramTokenizer.java:184)
            ...
            at org.apache.lucene.analysis.ngram.TestEdgeNGramTokenizerMaxGramIntegerMaxValue.testSeventeenCharText(TestEdgeNGramTokenizerMaxGramIntegerMaxValue.java:39)

# standalone runner
main 645d4fe14a20  -ea / -da   tests_run=1 failures=1   same ArrayIndexOutOfBoundsException at NGramTokenizer.java:184
10.6.0             -ea / -da   tests_run=1 failures=1   same
10.5.2             -ea / -da   tests_run=1 failures=1   same (CharacterUtils.toChars is line 111 there)

• Contract. @param maxGram the largest n-gram to generate (NGramTokenizer.java:91, :107; EdgeNGramTokenizer.java:38, :49). No upper bound and no note that large values fail, there, in the factories or in package-info.
• Intent in the code. "2 * maxGram in case all code points require 2 chars" (NGramTokenizer.java:130-132) and "Make the term att large enough" (:134): the wrap defeats both.
• CHANGES. 4.4.0, LUCENE-3907: "EdgeNGramTokenizer now supports maxGramSize > 1024" (lucene/CHANGES.txt:13581), with no upper limit.
• Siblings and history. EdgeNGramTokenFilter and NGramTokenFilter accept Integer.MAX_VALUE and give the right grams (executed). On 4.3.1 both tokenizers give the right grams for the same 16- and 17-char texts (executed; that version read at most 1024 chars).
• Nearby tokenizers. Several analysis tokenizers reject oversized length settings up front with an IllegalArgumentException: KeywordTokenizer and CharTokenizer in their constructors (KeywordTokenizer.java:41-48, CharTokenizer.java:71) and StandardTokenizer.setMaxTokenLength (StandardTokenizer.java:95-99), against MAX_TOKEN_LENGTH_LIMIT = 1024 * 1024 (StandardTokenizer.java:80).
• Maintainers (credit Robert Muir). On #8756 (LUCENE-7705), about size parameters of CharTokenizer and KeywordTokenizer: "I think Integer.MAX_VALUE is a trap for a number of reasons: enormous values will likely only blow up anyway (limited to 32766 in the index), if they don't they may create hellacious threadlocal memory usage in buffers, bad/malicious input could take out JVMs, etc.", and "Maybe follow the example of StandardTokenizer here", which led to MAX_TOKEN_LENGTH_LIMIT. On #6621 (LUCENE-5559, argument validation), about whether factories need their own checks: "if the factory would crash in some way that is confusing on certain inputs, then it would need a check too"; here neither the factories nor the tokenizer check. On #9395 (LUCENE-8348, open), a cost remark that proposes documentation, not a check: "it seems to surprise people that min=small, max=huge eats up a ton of resources".
• Tests. No upstream test uses a huge maxGram (TestNGramTokenizer and TestEdgeNGramTokenizer go up to 1300). TestRandomChains.java:176 keeps random int arguments in -50..50 because the full range "could cause huge ram usage": about allocation, not a wrap.

The strongest "works as designed" case (built by the intended-behaviour verifier): the buffers are sized from maxGram on purpose; the 4.4-4.10 EdgeNGramTokenizer javadoc warned that a maxGram larger than 1024 "will result in increased memory usage" (removed in 5.0); #9395 calls a huge max expensive; TestRandomChains avoids huge ints; configuration values are trusted (SECURITY.md:42). So Integer.MAX_VALUE can never be honoured as truly unbounded, and it fails loudly.

Why it fails: all of that is about cost, and the smaller huge values do fail fast at construction (OutOfMemoryError, or IllegalArgumentException: buffersize must be >= 2). As the adjudication put it: "That covers allocation cost or an OutOfMemoryError. It does not cover an accepted value wrapping into a tiny buffer and failing later with an internal-error exception." Nothing documents a limit. The adjudication kept the priority low and the confidence medium because the value is extreme.

Four options. Option A was validated with gradle in a scratch worktree at 645d4fe14a20; A', B and C were not executed. A rejecting fix (A, A', B) turns today's accidental success on texts of at most 16 chars into an error when the tokenizer is created; only C makes Integer.MAX_VALUE behave like maxGram = text length. A and A' also reject the contrived large-minGram settings that end a stream early.

Add a constant MAX_NGRAM_SIZE_LIMIT = (Integer.MAX_VALUE - 1025) / 3 (715,827,540) and, in init after the minGram > maxGram check, throw IllegalArgumentException("maxGram must not be greater than " + MAX_NGRAM_SIZE_LIMIT + ", got: " + maxGram). Why this bound: it keeps every buffer index sum within int even under a loose bound on the loop state (bufferStart <= bufferEnd <= 2 * maxGram + 1024, minGram <= maxGram). The largest such sum is bufferStart + 1 + minGram (NGramTokenizer.java:163), at most 3 * maxGram + 1025. The hunt's z3 model proves that the modelled sums (:130, :146, :162, :163, :195) cannot wrap up to this bound. It is a conservative choice, not a proven maximum, and it does not cover the stream char offsets (:188, :209), which depend on the stream length, not on maxGram.

/**
 * The largest accepted {@code maxGram}. The tokenizer buffers {@code 2 * maxGram + 1024} chars
 * and indexes that buffer with int arithmetic; this bound keeps those indexes in int range.
 */
public static final int MAX_NGRAM_SIZE_LIMIT = (Integer.MAX_VALUE - 1025) / 3;

// in init(), after the minGram > maxGram check
if (maxGram > MAX_NGRAM_SIZE_LIMIT) {
  throw new IllegalArgumentException(
      "maxGram must not be greater than " + MAX_NGRAM_SIZE_LIMIT + ", got: " + maxGram);
}

Trade-offs

• Integer.MAX_VALUE now fails when the tokenizer is created (for an Analyzer, when it first builds its components) instead of on the first long text; texts of at most 16 chars, which work by accident today, fail too.
• Values just below the bound are still accepted and need about 12 GB of buffers per tokenizer (about 16.5 bytes per unit of maxGram), so they fail with OutOfMemoryError unless the heap holds that, as today; the tests check the rejection, not that values near the bound are practical.
• Adds one public constant (it could be private); no other behaviour changes.

What the checks validated

• Gradle, scratch worktree at 645d4fe14a20, OpenJDK 25.0.3, -Ptests.seed=DEADBEEF: without the fix the minimal test fails; with it :lucene:analysis:common:checkGoogleJavaFormat and the whole :lucene:analysis:common:test task pass (340 suites, 1910 tests, 0 failures, 18 skipped), including the minimal test, TestNGramTokenizer 14, TestEdgeNGramTokenizer 15, TestNGramFilters 13, TestNGramTokenFilter 17, TestEdgeNGramTokenFilter 17 and TestConditionalTokenFilter 12.
• Shadowed onto the main jars: the minimal test passes with -ea and -da; the query probe and an independent probe get maxGram must not be greater than 715827540, got: 2147483647 for every Integer.MAX_VALUE case (both tokenizers, CustomAnalyzer, the IndexWriter and query paths) and for every boundary value from 1,073,741,312 up, while maxGram = 17, 1,000,000 and the token-filter control are unchanged.

Use StandardTokenizer.MAX_TOKEN_LENGTH_LIMIT (1024 * 1024) as the bound, as KeywordTokenizer and CharTokenizer do, and document it on the constructors.

Trade-offs

Matches those tokenizers and also removes most of the out-of-memory regime, but rejects values from 1,048,577 to 715,827,540, which work today when the heap is large enough. A maintainer's call. Not executed (the minimal test accepts it unchanged).

Compute the sizes with Math.multiplyExact / Math.addExact in init and rethrow an ArithmeticException as IllegalArgumentException.

Trade-offs

Rejects exactly the values whose sizes wrap (from 1,073,741,312); 715,827,541 to 1,073,741,311 stay accepted (they need more than 11 GB of buffers) and are outside the model's index-overflow proof. Not executed.

Size the buffers from a small value and grow the term buffer before the copy at NGramTokenizer.java:184 (and the read buffer when a gram needs more).

Trade-offs

The only option that makes Integer.MAX_VALUE behave like maxGram = text length, as the token filters do, but it changes the streaming loop and its memory profile: out of proportion for a rare setting. Not executed.

Method: executed differential testing, then a formal model.

• First signal. A planning probe in a hunt round on numeric limits of public API arguments ran NGramTokenizer(1, n) and EdgeNGramTokenizer(1, n) on a 28-char text against maxGram = text length, for boundary values of n: ArrayIndexOutOfBoundsException for 2^31-1 and 2^31-2, IllegalArgumentException for 2^30, OutOfMemoryError for 1,073,741,224 with a 1 GiB heap. The n-gram token filters, ShingleFilter and LimitTokenCountFilter passed as controls.
• Model. The finder modelled init's sizing and the index arithmetic of incrementToken in z3 with exact 32-bit wrap (21 queries): the exact partition of all maxGram values, and a bound (715,827,540) under which none of the modelled index sums can wrap.
• Translation validation. A bounded-exhaustive comparison of the real jar with an exact reference n-gram semantics (8.7 million tokenizations, minGram 1 to 3 and near maxGram). For Integer.MAX_VALUE with minGram 1 to 3 it found no silently wrong output. Its silent results for Integer.MAX_VALUE all have minGram = Integer.MAX_VALUE - 1 on a text longer than the 1022-char read buffer: no tokens, as expected, but a final offset of 1022 instead of the text length (an AssertionError with assertions on). That is the contrived large-minGram corner described above, not claimed.
• Reduction. A public-API JUnit test, later reduced to the single test shown here.