A FuzzyQuery wrapped in SpanMultiTermQueryWrapper is not capped at the clause limit, so it throws TooManyNestedClauses

FuzzyQuery documents that a maxExpansions above IndexSearcher#getMaxClauseCount is replaced by the limit, and its default top-terms rewrite does exactly that (TopTermsRewrite.rewrite keeps min(size, getMaxSize()) terms, and the core rewrites' getMaxSize() is the clause limit). SpanMultiTermQueryWrapper turns a top-terms rewrite into TopTermsSpanBooleanQueryRewrite(size) with the same size, documented as "will not overflow the boolean max clause count", but its TopTermsRewrite delegate returns Integer.MAX_VALUE from getMaxSize(), so it keeps up to maxExpansions terms. Since 9.0 (LUCENE-8811) IndexSearcher.rewrite counts every SpanTermQuery of the resulting SpanOrQuery and throws IndexSearcher$TooManyNestedClauses. So a FuzzyQuery(abcde, 2, 0, 2000, true) that keeps 1,024 of 1,326 matching terms and counts 676 documents on its own throws once span-wrapped; under a lowered limit (32) even the default FuzzyQuery (50 expansions) fails once wrapped. FrequentTermsSpanBooleanQueryRewrite (new in 10.6.0) has the same gap. The cap dates from 2010, when SpanOrQuery had no clause limit; the exception from 9.0.0. No wrong results, no index effect. The fix is two lines.

• Clause limit: IndexSearcher.getMaxClauseCount(), 1,024 by default (IndexSearcher.java:80, :251-261). IndexSearcher.rewrite visits the rewritten query and throws TooManyNestedClauses when the clause count goes over it (:878, :916-920).
• Top-terms rewrite: TopTermsRewrite keeps the best maxSize = Math.min(size, getMaxSize()) terms (TopTermsRewrite.java:64). The three core subclasses return the clause limit from getMaxSize() (MultiTermQuery.java:167-168, :212-213, :260-261). FuzzyQuery's default rewrite is one of them, TopTermsBlendedFreqScoringRewrite(maxExpansions) (FuzzyQuery.java:60-62; default maxExpansions 50, :56).
• Span rewrites: SpanMultiTermQueryWrapper maps any TopTermsRewrite to new TopTermsSpanBooleanQueryRewrite(getSize()) (SpanMultiTermQueryWrapper.java:70-78). FrequentTermsSpanBooleanQueryRewrite(n) (#16484, 10.6.0) can be set explicitly.

1. TopTermsSpanBooleanQueryRewrite's delegate overrides getMaxSize() with return Integer.MAX_VALUE; (SpanMultiTermQueryWrapper.java:208-211). TopTermsRewrite.rewrite then computes min(maxExpansions, Integer.MAX_VALUE): the clause limit is never applied, and the rewrite returns a SpanOrQuery of up to maxExpansions SpanTermQuerys.
2. FrequentTermsSpanBooleanQueryRewrite keeps the best terms in PriorityQueue.usingComparator(maxSize, order) (:312-314) and turns its own clause check off (:326-329). No clause cap either.
3. IndexSearcher.rewrite visits the SpanOrQuery (SpanOrQuery.java:87-93); each SpanTermQuery calls consumeTerms (SpanTermQuery.java:98-101), which counts one clause and throws TooManyNestedClauses once the count is over the limit (IndexSearcher.java:916-920). The check runs before the increment, so limit + 1 clauses pass and limit + 2 throw (open #10339, not part of this bug).
4. The sibling default rewrite still states the 2010 premise: "we accept all terms as SpanOrQuery has no limits" (:169-171). Since 9.0 that is no longer true.

Default limit 1,024; 676 documents with 1,326 distinct terms within two edits of abcde; FuzzyQuery(abcde, 2, 0, 2000, true): plain, 1,024 terms and 676 hits; span-wrapped, 1,326 span terms and TooManyNestedClauses. Limit 32, default FuzzyQuery: plain 32 terms; wrapped 50 terms, throws. maxExpansions 1024, 1025, 1026, 2000: plain always 676 hits; wrapped 676, 676, throws, throws. Explicit TopTermsSpanBooleanQueryRewrite(2000) and FrequentTermsSpanBooleanQueryRewrite(2000) on a 1,352-term prefix throw; a size equal to the limit works. Minimal repro: limit 2, four terms one edit from abcd: plain 2 hits, wrapped throws.

• Who is hit. Code that uses SpanMultiTermQueryWrapper around a FuzzyQuery or another top-terms multi-term query and either sets maxExpansions above the clause limit (relying on FuzzyQuery's documented cap), lowers the limit with IndexSearcher.setMaxClauseCount below the expansion size, or sets TopTermsSpanBooleanQueryRewrite(n) / FrequentTermsSpanBooleanQueryRewrite(n) with n above the limit.
• What it takes. The expansion must really match more terms than the limit (+1, because of #10339). Ordinary span-wrapped fuzzy queries (50 expansions, default limit 1,024) are not affected.
• What happens. Search, count and any other entry point that rewrites the query throw IndexSearcher$TooManyNestedClauses for that request, where the same query unwrapped runs with the capped expansion.
• What does not happen. No wrong results; nothing in the index or the searcher is changed; the clause limit still holds.
• Default vs opt-in. Default writer, codec and searcher settings, but every trigger needs a non-default size or a lowered limit on the spans API. No in-tree query parser builds this shape: no main source under lucene/queryparser names SpanMultiTermQueryWrapper or either span top-N rewrite (grep at 645d4fe14a20). Likelihood: rare; no user report was found in the nearly five years since 9.0.0.

Public API only: IndexWriter with the default IndexWriterConfig, ByteBuffersDirectory, TextField, IndexSearcher.setMaxClauseCount, FuzzyQuery, SpanMultiTermQueryWrapper, IndexSearcher.count; the class sits in the spans package by Lucene test convention but uses no package-private API, and it restores the static clause limit in finally. The catch only turns the exception into an expected-vs-actual message.

Why these numbers: the plain default FuzzyQuery (50 expansions) keeps 2 terms at limit 2 and counts 2 hits; wrapped, it keeps all 4, and 4 is the smallest clause count the visitor rejects at limit 2 (it lets limit + 1 through, #10339).

It fails unchanged on 10.6.0 and 10.5.2 with assertions on and off, and 5 of 5 iterations with another seed fail the same way on main (assertions on).

As the regression test: this same test, for example as a method in TestSpanMultiTermQueryWrapper. Either way (new file or new method), ./gradlew tidy (google-java-format) re-wraps two long lines (the comment and the AssertionError), which stay over 100 columns at the same indentation inside an existing class; nothing else changes.

cp TestSpanWrappedFuzzyQueryClauseLimit.java $LUCENE/lucene/queries/src/test/org/apache/lucene/queries/spans/
cd $LUCENE && ./gradlew :lucene:queries:test --tests org.apache.lucene.queries.spans.TestSpanWrappedFuzzyQueryClauseLimit -Ptests.seed=DEADBEEF
# assertions off: add -Ptests.asserts=false (same result)

TestSpanWrappedFuzzyQueryClauseLimit > testSpanWrappedFuzzyQueryIsCappedAtMaxClauseCount FAILED
    java.lang.AssertionError: expected 2 hits like the plain FuzzyQuery, got org.apache.lucene.search.IndexSearcher$TooManyNestedClauses: Query contains too many nested clauses; maxClauseCount is set to 2
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:40644820E53FDBCA]:0)
        at org.apache.lucene.queries.spans.TestSpanWrappedFuzzyQueryClauseLimit.testSpanWrappedFuzzyQueryIsCappedAtMaxClauseCount(TestSpanWrappedFuzzyQueryClauseLimit.java:53)

        Caused by:
        org.apache.lucene.search.IndexSearcher$TooManyNestedClauses: Query contains too many nested clauses; maxClauseCount is set to 2
            at org.apache.lucene.search.IndexSearcher$1.consumeTerms(IndexSearcher.java:918)
            at org.apache.lucene.queries.spans.SpanTermQuery.visit(SpanTermQuery.java:100)
            at org.apache.lucene.queries.spans.SpanOrQuery.visit(SpanOrQuery.java:93)
            at org.apache.lucene.search.ConstantScoreQuery.visit(ConstantScoreQuery.java:78)
            at org.apache.lucene.search.IndexSearcher.rewrite(IndexSearcher.java:878)
            at org.apache.lucene.search.IndexSearcher.count(IndexSearcher.java:497)
            at org.apache.lucene.queries.spans.TestSpanWrappedFuzzyQueryClauseLimit.testSpanWrappedFuzzyQueryIsCappedAtMaxClauseCount(TestSpanWrappedFuzzyQueryClauseLimit.java:50)

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF -Ptests.asserts=false; identical with assertions on

• Contract, in four javadocs. FuzzyQuery, @param maxExpansions: "the maximum number of terms to match. If this number is greater than IndexSearcher#getMaxClauseCount when the query is rewritten, then the maxClauseCount will be used instead." (FuzzyQuery.java:79-81). TopTermsRewrite constructor, which the span rewrite's delegate extends (the class is @lucene.internal, TopTermsRewrite.java:34): "NOTE: if IndexSearcher#getMaxClauseCount is smaller than size, then it will be used instead." (TopTermsRewrite.java:43-44). TopTermsSpanBooleanQueryRewrite: "only uses the top scoring terms so it will not overflow the boolean max clause count" (SpanMultiTermQueryWrapper.java:196-197). FrequentTermsSpanBooleanQueryRewrite, written in 2026: "retains only the most frequent terms so it will not overflow the boolean max clause count" (:258-259; also lucene/CHANGES.txt:519-521). On main BooleanQuery.Builder.add checks IndexSearcher.maxClauseCount (BooleanQuery.java:82): the only clause limit is IndexSearcher's.
• Long-standing intent. Lucene 1.9's CHANGES: "FuzzyQuery can no longer throw a TooManyClauses exception. If a FuzzyQuery expands to more than BooleanQuery.maxClauseCount terms only the BooleanQuery.maxClauseCount most similar terms go into the rewritten query" (lucene/CHANGES.txt:21672-21675).
• Upstream test. TestSpanMultiTermQueryWrapper.testFuzzy2 ("maximum of 1 term expansion") asserts that the wrapper honours a FuzzyQuery's maxExpansions (TestSpanMultiTermQueryWrapper.java:96-103).
• History. Integer.MAX_VALUE comes from the wrapper's introduction (ac71ebc2371, LUCENE-2754, 2010), when SpanOrQuery had no clause limit ("we accept all terms as SpanOrQuery has no limits", 1d0515124e2, LUCENE-2757, still at :169-171). LUCENE-8811 (53f56fb7ad4, 9.0) made IndexSearcher count every clause, span terms included, and touched no span file; spans are not mentioned in #9855. That the check reaches span expansions is by design: on #9855 Alan Woodward asked to run the count after rewriting because "some multi-term queries can end up expanding into very large boolean combinations, and we should try and catch that". What was not revisited is the span top-N rewrites' own cap, which the core top-terms rewrites apply before the check.

The strongest case for "intended" (rated moderate by the cross-model reviewers, partial by the study's intended-behaviour verifier): IndexSearcher.rewrite documents TooManyClauses for any query over the limit (IndexSearcher.java:868-869); LUCENE-8811 meant that check to catch large multi-term expansions; the span constructors promise only "at most size terms" (SpanMultiTermQueryWrapper.java:204, :305); the wrapper deliberately replaces FuzzyQuery's own rewrite with a span rewrite, so FuzzyQuery's cap describes a rewrite that does not run; TopTermsRewrite is @lucene.internal (TopTermsRewrite.java:34), so its NOTE is not part of the public span rewrite's contract, and its getMaxSize() javadoc says "for boolean rewrites" (:55-58); Integer.MAX_VALUE was a deliberate 2010 choice; and "boolean max clause count" could be read as BooleanQuery's only.

Why it fails: for the lead trigger the user never asks for more than the limit: they pass a maxExpansions that FuzzyQuery documents as capped, and the wrapper copies that size into its span rewrite (:72-74), which testFuzzy2 relies on. The two public span javadocs, not only the internal NOTE, say the rewrite "will not overflow", and on main there is no other "boolean max clause count" than IndexSearcher's. The check catching the expansion is intended; the span rewrite not capping before it is what differs from the core rewrites. The 2010 choice rested on "no limits", which 9.0 removed without revisiting spans. The argument keeps real weight for explicit span sizes above the limit, where a javadoc fix is a fair alternative (option C): a separate decision, not an equal defect. Verdict: not intended, a defect. Not security: the limit still holds and fails closed.

Fix A was validated by the focused gradle runs listed below in a scratch worktree of 645d4fe14a20; the full Lucene test suite was not run. B and C are alternatives that were not run.

Return the clause limit from TopTermsSpanBooleanQueryRewrite's getMaxSize() (SpanMultiTermQueryWrapper.java:210), so TopTermsRewrite.rewrite keeps min(size, limit) terms, and size the FrequentTerms queue min(maxSize, limit) (:313). Both read the limit when the query is rewritten, as FuzzyQuery documents.

--- a/lucene/queries/src/java/org/apache/lucene/queries/spans/SpanMultiTermQueryWrapper.java
+++ b/lucene/queries/src/java/org/apache/lucene/queries/spans/SpanMultiTermQueryWrapper.java
@@ -207,7 +207,7 @@
           new TopTermsRewrite<>(size) {
             @Override
             protected int getMaxSize() {
-              return Integer.MAX_VALUE;
+              return IndexSearcher.getMaxClauseCount();
             }
 
             @Override
@@ -310,7 +310,8 @@
           new ScoringRewrite<>() {
             @Override
             protected PriorityQueue<ScoreTerm> getTopLevelBuilder() {
-              return PriorityQueue.usingComparator(maxSize, order);
+              return PriorityQueue.usingComparator(
+                  Math.min(maxSize, IndexSearcher.getMaxClauseCount()), order);
             }
 
             @Override

Trade-offs

• Matches the three core top-terms rewrites exactly; a span-wrapped FuzzyQuery keeps the same top maxClauseCount terms as the plain one.
• Explicit TopTermsSpanBooleanQueryRewrite(n) / FrequentTermsSpanBooleanQueryRewrite(n) with n above the limit now keep maxClauseCount terms instead of throwing: what their "will not overflow" javadoc promises, but still a behaviour change.
• Parity with core, no more: a span-wrapped FuzzyQuery inside a SpanNearQuery with sibling clauses can still exceed the limit, exactly as BooleanQuery(a, b, fuzzy) does in core.
• Backport to branch_10_6: the same getMaxSize() line (:210); its FrequentTerms queue is new PriorityQueue<>(maxSize) {...} (:313), so cap that argument.

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20, seed DEADBEEF, 2026-11-01: without the fix the repro fails with assertions on and off; with it, it passes with assertions on and off.
• ./gradlew :lucene:queries:test --tests 'org.apache.lucene.queries.spans.*': 23 classes, 233 tests, 0 failures (2 skipped by the suite's own assumeTrue), including TestSpanMultiTermQueryWrapper, TestSpanSearchEquivalence, TestBasics and the repro.
• ./gradlew :lucene:queries:check -x test with the fix and the repro as a new test file: passes (google-java-format, ecj lint, forbidden APIs) once ./gradlew tidy re-wraps two long lines of the test; the fix itself needed no reformatting. The full Lucene test suite was not run.
• Earlier: with the fix shadowed into the stock jars, the finder's, the independent reproduction's and the adjudication's tests and 73 upstream span tests pass, and the study's boundary checker finds no span top-N mismatch (its 8 record-only rows for the unbounded default rewrite remain).

new TopTermsSpanBooleanQueryRewrite(Math.min(pqsize, IndexSearcher.getMaxClauseCount())) at SpanMultiTermQueryWrapper.java:74. Fixes the wrapped-FuzzyQuery case without touching explicit sizes.

Trade-offs

• Reads the limit when the wrapper is built, not when the query is rewritten, so a later setMaxClauseCount is ignored (FuzzyQuery says "when the query is rewritten").
• The two "will not overflow" javadocs stay false for explicit sizes.

Keep explicit sizes uncapped and replace "will not overflow the boolean max clause count" (:196-197, :258-259) with "throws TooManyNestedClauses at search time if more than IndexSearcher#getMaxClauseCount terms match".

Trade-offs

Honest about today's behaviour for explicit sizes, but does not fix the FuzzyQuery case on its own (combine with B).

Method: bounded-exhaustive boundary translation validation of the stock jar against each entry point's javadoc, public API only (study unit on documented resource limits, main a9779ef3c193, 2026-10-27).

• Inventory: a grep of javadoc sentences that name a numeric limit with a consequence (TooManyClauses, maxExpansions, "at most", ...) over core, queries, suggest, analysis-common and queryparser, then a reading of every call site that reaches the limited computation; the span rewrites' Integer.MAX_VALUE was flagged there.
• Checker: 915 checks: clause limit L = 1..8, n in {L - 1, L, L + 1} matching terms, sizes {L - 1, L, L + 1, 2L}, 18 entry points (BooleanQuery.Builder, SynonymQuery, the core top-terms and scoring rewrites, FuzzyQuery, the span rewrites, QueryBuilder, the classic parser, ...), expected outcome per entry point from its javadoc.
• Result: 48 mismatches, all in the span-wrapped FuzzyQuery, TopTermsSpanBooleanQueryRewrite and FrequentTermsSpanBooleanQueryRewrite (they keep L + 1 terms at n = L + 1 where the core rewrites keep L), 0 in 14 others. The 18th entry, a record-only check of the unbounded default span rewrite (SCORING_SPAN_QUERY_REWRITE, out of scope: #7571, #10339), logged 8 more: at n = L + 1 it lets L + 1 terms through where the javadoc model expects a throw, the known clause-visitor off-by-one. A mutant that adds one to the core rewrites' getMaxSize() gives 16 mismatches per core entry point, so the checker is not vacuous; the fix removes every span top-N mismatch and leaves the 8 record-only rows.
• A scale probe at the default limit 1,024 gave the lead trigger; the finder then wrote the public-API JUnit, and the one-test minimal repro was reduced from it.