QueryParserHelper.setQueryNodeProcessor(null) throws NullPointerException although its javadoc allows null

The flexible query parser runs three phases: a syntax parser builds a tree of query nodes, an optional processor rewrites it, and a builder turns it into a Query. QueryParserHelper.setQueryNodeProcessor documents that its argument "can be null, which means that no processor will be used to process the query node tree" (QueryParserHelper.java:92-96 at 645d4fe14a20). The body stores the argument (:101) and then calls this.processor.setQueryConfigHandler(getQueryConfigHandler()) without a null check (:102), so the documented call always throws NullPointerException. The constructor (:71), setQueryConfigHandler (:189) and parse (:218) all skip a null processor. StandardQueryParser and PrecedenceQueryParser inherit the setter. The defect dates from the commit that created the class (LUCENE-1567, 2009) and is in every release from 2.9.0 to 10.6.0 and on main. No query comes out wrong: the field is already null when it throws, and code that builds a QueryParserHelper itself can pass null to its constructor instead.

1. Three phases, one optional. parse runs the syntax parser (:214), then the processor only if (processor != null) (:216-220), then the builder (:222). The package doc: "at least 2 phases, text parsing and query building, and one optional phase called query processing" (package-info.java:25-26).
2. Every other entry point handles "no processor". The constructor calls processor.setQueryConfigHandler(queryConfigHandler) only if (processor != null) (:61-74, guard :71); setQueryConfigHandler does the same (:185-192, guard :189); the getter documents a null result "if no processor is used" (:76-87).
3. The setter forgets the guard (:100-103), right under the javadoc that allows null (:89-99):

public void setQueryNodeProcessor(QueryNodeProcessor processor) {
  this.processor = processor;                                   // :101
  this.processor.setQueryConfigHandler(getQueryConfigHandler()); // :102  NPE when processor == null
}

1. The state is already right when it throws. Line 101 runs first, so afterwards getQueryNodeProcessor() is null and parse("Foo", "f") gives f:Foo, exactly the documented no-processor parser. Only the exception is wrong.
2. Who inherits it. StandardQueryParser extends QueryParserHelper (StandardQueryParser.java:231) and PrecedenceQueryParser extends StandardQueryParser (PrecedenceQueryParser.java:35); neither overrides the setter. The only callers in the Lucene tree are the two PrecedenceQueryParser constructors, which pass a new non-null pipeline (:41, :50); no test calls the setter (tests do assume the default pipeline: TestQPHelper.java:165 casts getQueryNodeProcessor() to QueryNodeProcessorPipeline).

• Who is hit. Applications that switch the processing phase off on an existing parser through setQueryNodeProcessor(null): a custom QueryParserHelper that builds the raw syntax tree, or code that swaps processors and clears one. It fails every time, deterministically, in the setter itself, whether or not the parser has parsed queries before.
• Default vs opt-in. Opt-in and rare. StandardQueryParser and PrecedenceQueryParser never pass null. For StandardQueryParser, turning processing off switches off all 21 processors of its pipeline: analysis and the default operator, and also wildcard, regexp, fuzzy, range, point, multi-field, phrase-slop, boost, rewrite-method and interval handling and the tree clean-ups; StandardQueryTreeBuilder says it "should be used" on a tree processed by that pipeline (StandardQueryTreeBuilder.java:45-48). So it is an unusual setup, not a general raw-parser mode, and the runs here cover only the single-term query Foo. GitHub searches of Elasticsearch, OpenSearch and Solr found no use of setQueryNodeProcessor.
• Effect. A loud NullPointerException: no wrong query, no index or data effect, constant cost. The harm is a documented call that cannot be used, and a confusing NPE for the user who followed the javadoc.
• Workaround. Code that builds a QueryParserHelper itself (or a subclass that calls super(...)) can pass null as the processor to its four-argument constructor. StandardQueryParser and PrecedenceQueryParser have no constructor that takes a processor, so their users build new QueryParserHelper(new StandardQueryConfigHandler(), new StandardSyntaxParser(), null, new StandardQueryTreeBuilder()) instead (executed: parse("Foo", "f") = f:Foo). Or catch the NPE (the field is already set).

The try/catch only turns the NPE into an AssertionError that states expected vs actual; without it the test shows the bare NPE. Nothing random reaches the code path; the seed only satisfies the test framework.

Suggested regression test: this same test, as its own class or as one method in TestQPHelper.

# main 645d4fe14a20, gradle, seed DEADBEEF, -Ptests.asserts=false (the same with true)
TestSetNullQueryNodeProcessor > testSetNullProcessor FAILED
    java.lang.AssertionError: expected null to switch off query processing, got java.lang.NullPointerException: Cannot invoke "org.apache.lucene.queryparser.flexible.core.processors.QueryNodeProcessor.setQueryConfigHandler(org.apache.lucene.queryparser.flexible.core.config.QueryConfigHandler)" because "this.processor" is null
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:3B1758AF574D57D9]:0)
        at org.apache.lucene.queryparser.flexible.standard.TestSetNullQueryNodeProcessor.testSetNullProcessor(TestSetNullQueryNodeProcessor.java:31)

        Caused by:
        java.lang.NullPointerException: Cannot invoke "org.apache.lucene.queryparser.flexible.core.processors.QueryNodeProcessor.setQueryConfigHandler(org.apache.lucene.queryparser.flexible.core.config.QueryConfigHandler)" because "this.processor" is null
            at org.apache.lucene.queryparser.flexible.core.QueryParserHelper.setQueryNodeProcessor(QueryParserHelper.java:102)
            at org.apache.lucene.queryparser.flexible.standard.TestSetNullQueryNodeProcessor.testSetNullProcessor(TestSetNullQueryNodeProcessor.java:29)
:lucene:queryparser:test (FAILURE): 1 test, 1  failure

# the same NPE at QueryParserHelper.java:102 with the 9.12.3, 10.5.2 and 10.6.0 release jars (-da)
# with the null-guard fix: 1 test, 0 failures (assertions on and off)

• The contract allows null twice and says what it means: "The argument can be null, which means that no processor will be used to process the query node tree" (QueryParserHelper.java:92-93) and "@param processor ... this argument can be null" (:95-96). The getter: "it returns null if no processor is used" (:77-78).
• The package design makes processing optional: "one optional phase called query processing" (package-info.java:25-26); "Second (optional) Phase: Query Processing" (:36); "This phase is optional" (:41).
• The class handles null everywhere else: constructor (:71), setQueryConfigHandler (:189), parse (:218).
• Null handling was chosen setter by setter: setSyntaxParser and setQueryBuilder document "cannot be null" (:106-107, :123-124) and throw IllegalArgumentException (:115-117, :132-134); setQueryConfigHandler documents "It can be null" (:177-178) and accepts it.
• Tests and history: no test passes null to the setter or asserts the NPE, and no CHANGES or MIGRATE entry names it. The javadoc, the unguarded call and the guarded constructor were written in the same commit, 343992fcbb4 (LUCENE-1567, 2009); later commits never changed the setter's code or the wording of its javadoc: one renamed getTextParser to getSyntaxParser (565a6d22b5f, LUCENE-1792, 2009-08-19, before 2.9.0); the others moved the file, edited its license header and javadoc HTML, or reformatted it (last: LUCENE-9570, 2cbf261032d, 2021, which only reflowed the setter). No discussion (#2641, #2856, #14168) accepts the NPE.

Strongest case (from the intended-behaviour checker): the javadoc is stale on an expert hook; no caller or test has passed null in 17 years and nobody reported it; Lucene often treats null arguments as caller errors; the constructor is a workaround (for code that builds the helper itself); so the docs, not the code, should change.

Why it fails: the permission is repeated in the @param, matched by the getter's documented state and the package's "optional phase", and implemented by the class's three other code paths. Where the authors wanted to refuse null, they said so and threw IllegalArgumentException. A doc-only change would leave the constructor, the getter, parse and the package doc saying the opposite. The cross-model reviewer rated the intended argument weak.

The recommended fix was applied with git apply to a scratch worktree of 645d4fe14a20 and run through gradle; the alternative was not run.

In setQueryNodeProcessor (QueryParserHelper.java:100-103), call setQueryConfigHandler only when the new processor is not null.

public void setQueryNodeProcessor(QueryNodeProcessor processor) {
  this.processor = processor;
  if (processor != null) {
    processor.setQueryConfigHandler(getQueryConfigHandler());
  }
}

Trade-offs

None found. The setter then does what its javadoc says and matches the constructor (:71-73) and setQueryConfigHandler (:189-191); a non-null argument is configured as before in single-threaded use (the fix calls the method on the parameter, which line 101 has just stored in the field; the class has no synchronisation either way).

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20 with the repro test added, seed DEADBEEF: the repro test passes with -Ptests.asserts=false; the whole :lucene:queryparser:test (31 classes, 534 tests including the repro) passes with assertions on: 0 failures, 1 skipped. The same suite without the fix: 1 failure, the repro.
• :lucene:queryparser:checkGoogleJavaFormat passes with the fix.
• Standalone runner with the fixed class shadowed: the repro passes with -ea and -da.
• The hunt's 150-test flexible-parser subset passes stock and with this guard and the hunt's two other fix sketches (in QueryNodeImpl and QueryNodeProcessorPipeline) applied together; the 534-test module run is the one with this guard alone.

Rewrite the setter's javadoc and @param and throw IllegalArgumentException, like setSyntaxParser and setQueryBuilder (:113-120, :130-137). Not run.

Trade-offs

Replaces the NPE with a clear message, but removes a documented mode and leaves the class inconsistent: the constructor still accepts null, the getter still documents it, parse still skips it, and the package doc still calls processing optional.

Method: non-formal (code reading, then a directed JUnit), 2026-10-28, main a9779ef3c193. The hunt unit's lead was the list views of QueryNodeProcessorPipeline; QueryParserHelper was one of its files. Reading the class showed that the constructor, setQueryConfigHandler and parse guard a null processor and the setter does not. The finder's JUnit (the setter through StandardQueryParser, plus a constructor control) failed 1 of 2 on main (-ea and -da), branch_10_6, 10.5.2 and 9.12.3. A later minimisation step replaced it with the one-method test shown here.