Surround QueryParser.parse throws StackOverflowError instead of its declared ParseException on deeply nested groups

org.apache.lucene.queryparser.surround.parser.QueryParser.parse(String), the surround parser's documented client entry point, declares only ParseException, and its parse2 turns the generated lexer's TokenMgrError (a java.lang.Error) into one. The JavaCC grammar is recursive descent with no depth bound: FieldsQuery -> OrQuery -> AndQuery -> NotQuery -> NQuery -> WQuery -> PrimaryQuery('(' FieldsQuery ')') costs seven method frames per group, and prefix operators such as OR(a, b) re-enter FieldsQuery the same way. So valid input with deep nesting exhausts the thread stack and java.lang.StackOverflowError escapes parse. On a 1 MB stack, as few as 736 nested groups (1,473 chars) overflowed (the first overflow of a depth search after 3,000 shallow parses); on the 2 MB aarch64 default stack about 1,550; in later deep parses in the same JVM the limit rose roughly 9 to 16 times, and 100,000 groups always fail. Nothing else goes wrong: no wrong query, no index effect, and later parses work. The bug is in the parser's first commit (2005) and in every release from 1.9 to 10.6.0. A nesting counter in QueryParser.jj, as #16423 added to the expressions parser, fixes it.

• Group: a parenthesised subquery, ( ... ), or the argument list of a prefix operator, OR(a, b).
• ParseException: the checked exception the surround parser declares for input it cannot parse (ParseException.java:5-7: "thrown when parse errors are encountered").
• TokenMgrError: what the generated lexer throws on a bad character; it extends Error (TokenMgrError.java:7). parse2 converts it into ParseException.

1. QueryParser.parse(String) (QueryParser.java:53-56) declares only throws ParseException, builds a new parser and calls parse2. The class javadoc (:21-22) says it is "The only method that clients should need to call".
2. parse2 (:62-69; grammar source QueryParser.jj:97-104) wraps TopSrndQuery() in catch (TokenMgrError tme) { throw new ParseException(tme.getMessage()); } and catches nothing else.
3. Every group costs seven frames: FieldsQuery (:151, calls OrQuery at :155) -> OrQuery (:186, :190) -> AndQuery (:218, :222) -> NotQuery (:250, :254) -> NQuery (:282, :286) -> WQuery (:313, :317) -> PrimaryQuery (:344), whose ( branch calls FieldsQuery again (:351; QueryParser.jj:379, <LPAREN> q = FieldsQuery() <RPAREN>). Prefix operators take a second path, PrefixOperatorQuery -> FieldsQueryList -> FieldsQuery (QueryParser.jj:388-420). Each FieldsQuery also runs a short lookahead (OptionalFields -> jj_2_1 -> jj_3_1 -> jj_scan_token, :162-167, :577-590, :700-704), where many overflow traces end.
4. Nothing counts the depth: the surround package has no depth or nesting check and no StackOverflowError handling. The module's only complexity limit, the default BasicQueryFactory's 1,024 basic queries (BasicQueryFactory.java:25, :39-41), counts the term queries made when the query is rewritten against an index for search (checkMax, :68-71, called from SimpleTermRewriteQuery.rewrite, SimpleTermRewriteQuery.java:36-53), long after parsing.
5. So deep enough nesting fills the thread stack, and the StackOverflowError passes through parse2 to the caller.

x86_64 was not measured, so these thresholds are aarch64 figures; the JVM's default thread stack on Linux x86_64 is 1 MB (the platform default). Lucene's gradle test JVMs run with -XX:TieredStopAtLevel=1, so JUnit thresholds can differ from standalone runs.

• Who. Code that calls org.apache.lucene.queryparser.surround.parser.QueryParser.parse(String) (or parse2) on text it does not bound: a search box or request parameter that accepts surround syntax, or a program that generates surround queries.
• Default vs opt-in. The surround parser itself is opt-in and niche, but it fails with its default settings: there is no setting or API to limit nesting.
• Scale. Hundreds to a few thousand nested groups, depending on the stack size and on what the JVM has parsed before: as few as 736 (1,473 chars) on a 1 MB stack after shallow warm-up parses, about 1,550-2,000 on the 2 MB aarch64 default. A query builder that parenthesises every binary OR reached it at 740-800 terms on a 1 MB stack after earlier parses in the same JVM (a fresh JVM parsed 800), within the default 1,024-basic-query limit; on the 2 MB stack chains up to 1,020 terms parsed.
• Effect. The caller gets java.lang.StackOverflowError where it expects a query or ParseException. A handler that catches only ParseException or Exception misses it, so the error reaches whatever handles Errors on that thread. No wrong query is built, nothing is written to an index, and the parser keeps no state across calls (parse builds a new parser; STATIC=false, QueryParser.jj:24), so the next parse works.
• How likely. Rare: nobody types hundreds of nested groups, and the recorded search found no prior public report.

One test class on Lucene's test framework (LuceneTestCase only as the base class), one method, queryparser module, deterministic, single thread, no index. It accepts either declared outcome, a query or a ParseException, so it also passes with any fix that rejects too-deep input. Create lucene/queryparser/src/test/org/apache/lucene/queryparser/surround/parser/ (it does not exist on main) and copy it there (the package parse2 lives in; the test uses only the public static parse).

The small inputs show it better than 100,000 levels, each with its condition: 900 nested groups (1,801 chars) overflowed a 1 MB stack (-Xss1m) after 3,000 shallow parses (4 of 4 JVMs), and an 800-term chain ((t0 OR t1) OR t2) ... overflowed it after 20,000 warm-up parses. They are measurements, not part of the repro, because whether they overflow depends on the stack size and on what the JVM has parsed before; a fresh JVM parsed both.

TestSurroundDeepNesting > testDeeplyNestedGroups FAILED
    java.lang.AssertionError: expected a query or ParseException, got StackOverflowError
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:6401D84E5BDA89A4]:0)
        at org.apache.lucene.queryparser.surround.parser.TestSurroundDeepNesting.testDeeplyNestedGroups(TestSurroundDeepNesting.java:30)

        Caused by:
        java.lang.StackOverflowError
            at org.apache.lucene.queryparser.charstream.FastCharStream.readChar(FastCharStream.java:51)
            at org.apache.lucene.queryparser.charstream.FastCharStream.BeginToken(FastCharStream.java:84)
            at org.apache.lucene.queryparser.surround.parser.QueryParserTokenManager.getNextToken(QueryParserTokenManager.java:506)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.jj_scan_token(QueryParser.java:704)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.jj_3_1(QueryParser.java:590)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.jj_2_1(QueryParser.java:581)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.OptionalFields(QueryParser.java:167)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.FieldsQuery(QueryParser.java:154)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.PrimaryQuery(QueryParser.java:351)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.WQuery(QueryParser.java:317)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.NQuery(QueryParser.java:286)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.NotQuery(QueryParser.java:254)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.AndQuery(QueryParser.java:222)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.OrQuery(QueryParser.java:190)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.FieldsQuery(QueryParser.java:155)
            at org.apache.lucene.queryparser.surround.parser.QueryParser.PrimaryQuery(QueryParser.java:351)
            ... (the seven-frame cycle repeats)

:lucene:queryparser:test (FAILURE): 1 test, 1  failure

• The declared failure mode is ParseException. parse(String) declares only throws ParseException (QueryParser.java:53), and parse2 converts the generated lexer's TokenMgrError, an Error, into one (:62-69), so the code does not mean to let Errors reach callers on bad input. No javadoc says so in words: the expectation is implied by the throws clause and the conversion.
• The input is valid. (a), ((a)) and 50 nested groups parse to the same query as a; the surround docs and grammar allow groups at any depth, and nothing documents a limit. The surround tests treat ParseException as the parser's failure channel (Test01Exceptions.java:32-62, "No ParseException for:").
• The same module already converts errors. StandardSyntaxParser.parse catches Error and throws its declared QueryNodeParseException (StandardSyntaxParser.java:88-101, catch at :95).
• The project fixed the same shape elsewhere. #16423 (merged 2026-07-27, approved by rmuir and msokolov) added a nesting limit, default 1,024, to the expressions parser, which "could throw StackOverflowError on deeply nested expressions" and "no longer throws virtual machine errors" (lucene/CHANGES.txt:551-555); it keeps a StackOverflowError catch as a fallback (JavascriptCompiler.java:266-271).
• No way around it for callers except bounding the text themselves: there is no nesting option, and BasicQueryFactory's 1,024-basic-query limit counts the term queries made when the query is rewritten against an index for search (BasicQueryFactory.java:25, :68-71; SimpleTermRewriteQuery.java:36-53), long after the parser has overflowed.
• History. The catch and the unbounded recursion are both in the parser's first commit (2005); no commit, test or discussion mentions nesting depth.

The strongest case for "intended" (rated moderate by the cross-model reviewer, OpenAI GPT-5.6, and by the intended-behaviour devil's advocate): a Java throws clause never covers VirtualMachineErrors; ParseException is about parse errors and deep nesting is not one; SECURITY.md:38 names "deeply nested queries" among inputs whose limits are "the responsibility of the downstream application"; on #7218 (2015, RegExp) rmuir called a stack overflow the embedder's stack-size problem, and on #752 (2022) rmuir and msokolov rejected catching StackOverflowError; #16423 and #11510 were filed as enhancements.

Why it fails: the input is small (1.5 to 4 KB) and valid, and the caller has no API to bound nesting; SECURITY.md:46 says such out-of-scope issues "are still valid bug reports and hardening suggestions"; msokolov's #752 objection was to the technique ("If we could somehow detect the problem before it gets to that, then throwing IAE would make sense"), which is what a nesting counter does; and the same maintainers approved exactly that fix, with a fallback catch, for the expressions parser in #16423. What remains is a classification risk: maintainers may label it an improvement.

Fix A was implemented in the grammar, regenerated with JavaCC through gradle and run (diff below). B was run earlier as a shadow of the generated file only. C and D were not run.

enterGroup() increments nestingDepth after each <LPAREN> in PrimaryQuery and FieldsQueryList and throws ParseException past MAX_NESTING_DEPTH (1,024); the matching <RPAREN> decrements it. parse2 resets the counter and converts a StackOverflowError that still happens into ParseException("Nesting level too deep") with the error as cause. Regenerated with ./gradlew :lucene:queryparser:regenerateSurroundQueryParser (+25/-3 in QueryParser.jj, +26 in the generated QueryParser.java, the checksum file).

  ( <LPAREN> {enterGroup();} q = FieldsQuery() <RPAREN> {nestingDepth--;}
  | q = PrefixOperatorQuery()
  ...
  private void enterGroup() throws ParseException {
    if (++nestingDepth > MAX_NESTING_DEPTH) {
      throw new ParseException(
          "Nesting level too deep: more than " + MAX_NESTING_DEPTH + " nested groups");
    }
  }

Trade-offs

• When the stack holds 1,024 levels (the 2 MB default did, in these runs), the counter rejects deeper input deterministically; on a smaller stack the overflow can come first, and the fallback turns it into ParseException (tested configurations only). It covers every recursion path: the grammar re-enters FieldsQuery only through PrimaryQuery's ( and FieldsQueryList; operator chains and field prefixes are loops. It bounds nesting, not input size. One int increment per group, nothing on the hot search path.
• 1,024 matches #16423 and the module's 1,024-basic-query limit (a binary OR chain within that limit nests at most 1,023 deep). But a 1 MB stack can run out first: after 3,000 shallow parses, 900 groups overflow there, so the fallback catch, not the counter, turns them into ParseException (executed), and whether a 900-group query parses still depends on the stack. A lower limit avoids that but rejects deep machine-built queries that parse today.
• Adds a public constant (MAX_NESTING_DEPTH); maintainers may prefer a configurable limit, as JavascriptCompiler.compile(..., maxNestingDepth) has.
• The fallback is a catch of StackOverflowError, which rmuir and msokolov objected to on #752 as the only fix; #16423 keeps the same fallback behind its counter.

What the checks validated

Executed 2026-10-31 in a scratch worktree of 645d4fe14a20 with OpenJDK 25.0.3, gradle --no-daemon, seed DEADBEEF:

• Stock: the repro fails with assertions on and off (expected a query or ParseException, got StackOverflowError).
• Regenerated with ./gradlew :lucene:queryparser:regenerateSurroundQueryParser (JavaCC through gradle): the generated QueryParser.java changes only by the counter, enterGroup() and the catch; the regenerate checksum file is updated.
• With fix A: the whole :lucene:queryparser:test passes, 538 tests including the repro and 4 validation-only methods, 1 skipped (assertions on); the repro and the validation methods also pass with assertions off; regenerateSurroundQueryParserChecksumCheck, checkGoogleJavaFormat, forbiddenApisMain and ecjLintMain pass.
• Validation-only methods (not the repro): 1,024 nested groups parse to the same query as a; 1,025 give ParseException: Nesting level too deep: more than 1024 nested groups; 1,025 nested OR(b, ...) prefix lists are rejected; a parser instance parses again after a rejection.
• Probe outside the test framework (assertions off; 3,000 shallow parses first; two JVMs per row): at -Xss1m stock overflows from 900 groups, fix A returns ParseException: Nesting level too deep with a StackOverflowError cause from 900 to 100,000 groups (the fallback); on the 2 MB default stack stock overflows at 2,000, fix A parses up to 1,024 and rejects 1,025 and more through the counter. With one parse per fresh JVM, fix A rejects 1,025 and more through the counter on both stacks.

Not run: other modules (nothing else in the repository calls the surround parser), x86_64, and a benchmark (the change adds one int increment per group to parsing only).

The finder's sketch: next to the TokenMgrError catch, catch (StackOverflowError soe) throws ParseException("Nesting level too deep") with the cause.

Trade-offs

Smallest change, and it made the repro and the independent reproducer's tests pass (run as a shadow of the generated QueryParser.java, which a real patch must instead change through QueryParser.jj). But which inputs fail still depends on stack size and JIT state, the parser first recurses until the stack is full, and catch-only is the technique maintainers rejected on #752.

Fix A without the catch in parse2.

Trade-offs

Never catches an Error, but with a 1,024 limit it leaves a StackOverflowError window on 1 MB stacks (as few as 736 groups after warm-up); closing it needs a much lower limit, which rejects valid queries that parse today. Not run.

Open issue #16820 proposes deprecating the surround parser for Lucene 11.

Trade-offs

Does not change any 10.x release, which stays affected; users of the parser would still need A or B there. Not a fix on its own.

Method: semi-formal. The lead was the hunt plan's hypothesis that parsers of user query text are siblings of #16423; tools then witnessed it.

• Static model. GuardScan builds the call graph of the real queryparser bytecode, finds the recursive strongly connected components reachable from 25 public parse entry points over edges with no depth guard and no Error conversion, and predicted that surround parse and parse2 can leak StackOverflowError through a nine-method grammar cycle. On a jar with the fix sketch it reports no leak.
• Depth sweep. DepthSweep ran one JVM per -Xss: the smallest overflowing depth was 121, 326 and 736 at 256 KB, 512 KB and 1 MB.
• Reduction. A public-API JUnit on the stock jar (100,000 nested groups), later cut to the one-test repro shown here.
• Checked by an independent reproducer, a cross-model reviewer, an intended-behaviour devil's advocate, an adjudication, a history and a prior-report follow-up, a credibility audit and this brief's gradle runs (below).