CompletionWeight returns a scorer supplier with a null bulk scorer, so IndexSearcher#search of a CompletionQuery throws NullPointerException on a segment it cannot match

Weight#scorerSupplier "must return null if the scorer is null" (Weight.java:142 on main 645d4fe14a20), and IndexSearcher#searchLeaf relies on it: it skips a segment only when the supplier is null and otherwise calls score() on the supplier's bulk scorer without a null check (IndexSearcher.java:842-852). CompletionWeight#scorerSupplier returns a supplier for every segment (CompletionWeight.java:93-137); its bulkScorer() returns null when the segment has no terms for the suggest field (:108), has no FST for it (:114), or the query's BitsProducer filter returns Bits.MatchNoBits (:125); the first and third were executed, the no-FST case is by code reading only. So a CompletionQuery run through IndexSearcher#search(Query, CollectorManager) with TopSuggestDocsCollectors, or through the search method SuggestIndexSearcher inherits, throws NullPointerException on such a segment; with a query timeout, TimeLimitingBulkScorer's requireNonNull throws it first (TimeLimitingBulkScorer.java:64-66). SuggestIndexSearcher#suggest, the documented entry point, goes through the Weight#bulkScorer helper and skips the null (SuggestIndexSearcher.java:69-71), so it is not affected. It is a regression in 10.0.0 from #13408 (ddf538d43e9), which moved this weight's three return null lines from the overridden Weight#bulkScorer, which 9.x IndexSearcher null-checked, into ScorerSupplier#bulkScorer: the same call (no query timeout) returns exactly suggest()'s suggestions on 8.11.4 to 9.12.3 and throws on every executed 10.x release, 10.6.0 (branch_10_6) and main. The search fails loudly; nothing is corrupted, and this bug returns no wrong results. The fix returns null from scorerSupplier in the three cases.

• Weight / ScorerSupplier / BulkScorer: a query's per-search Weight gives, per segment, a ScorerSupplier, which gives the BulkScorer that feeds matches to a collector. Weight.java:142: "It must return null if the scorer is null." Weight.java:145: "@return a ScorerSupplier providing the scorer, or null if scorer is null". ScorerSupplier.java:39-46 documents no null from bulkScorer(); its default wraps get(), which "may not return null" (:29).
• Document suggester: SuggestField indexes suggestions into an FST per segment (a dedicated completion postings format); a CompletionQuery (PrefixCompletionQuery, RegexCompletionQuery, FuzzyCompletionQuery, ContextQuery) finds the top suggestions. An optional BitsProducer filter restricts the documents per segment. CompletionQuery.java:36 recommends SuggestIndexSearcher#suggest to run them.
• TopSuggestDocsCollector: the only collector CompletionScorer#score accepts (CompletionScorer.java:69-72), so it is what a caller of IndexSearcher#search(Query, CollectorManager) uses.

1. IndexSearcher.java:842-843: searchLeaf asks weight.scorerSupplier(ctx) and skips the segment only if it is null.
2. :844-852: otherwise it calls bulkScorer(), wraps it in a TimeLimitingBulkScorer when a timeout is set (:846-848) and calls score() on it (:852). No null check.
3. CompletionWeight.java:93-137: scorerSupplier always returns new ScorerSupplier() {...} (its get and cost throw UnsupportedOperationException). The supplier's bulkScorer() returns null at :108 (no terms for the field), :114 (no FST, "a segment can have a null suggester") and :125 (the filter returned Bits.MatchNoBits).
4. So on such a segment searchLeaf calls score() on null: NullPointerException ... because "scorer" is null at IndexSearcher.java:852. With a timeout, TimeLimitingBulkScorer's constructor (Objects.requireNonNull, :64-66) throws first.
5. SuggestIndexSearcher.java:64-86: suggest loops over the segments itself, calls the final Weight#bulkScorer helper (Weight.java:170-179, which returns null for a null supplier and otherwise scorerSupplier.bulkScorer()), and skips a null result (:71). That is why suggest() works.

Index: segment _0 with SuggestField("sug", "apple" + i, i + 1) for i = 0..2, segment _1 with one document without the field. suggest(q, 5, false) returns 3: doc 2 apple2 3.0, doc 1 apple1 2.0, doc 0 apple0 1.0. On main, weight.scorerSupplier(leaf) is non-null on both leaves, and supplier.bulkScorer() is a CompletionScorer on leaf 0 and null on leaf 1; IndexSearcher#search(q, manager(5)) throws the NPE at IndexSearcher.java:852. On 9.12.3 the same IndexSearcher#search returns the same 3 suggestions. A one-segment index with a MatchNoBits filter: suggest() returns 0, IndexSearcher#search throws.

• Who is exposed. Code that runs a CompletionQuery through IndexSearcher#search(Query, CollectorManager), for example to send every query type through one search entry point, or through the search method SuggestIndexSearcher inherits from IndexSearcher. SuggestIndexSearcher#suggest users are not affected. Elasticsearch and OpenSearch run completion queries through their own per-segment loop with a null check, as suggest() does (read 2026-10-28), so they are not affected; Solr has no CompletionQuery user.
• Default configuration. Default codec (plus the completion postings format that SuggestField needs), default IndexWriterConfig, a plain IndexSearcher.
• Deterministic once on that path. Every such search fails once it reaches a segment without a document that has the suggest field (an ordinary index state when only some documents carry suggestions; how common it is in practice was not measured) or a segment for which the query's filter returns Bits.MatchNoBits (possible on a one-segment index; Lucene's own TestSuggestField#testSuggestOnAllFilteredDocuments uses such a filter with suggest()). The third trigger, a segment with the field but no FST, is by code reading only.
• Upgrade trap. The same code runs without an exception on 9.x (and, without a query timeout, returns exactly suggest()'s suggestions) and fails after upgrading to 10.x.
• Effect. A NullPointerException from inside IndexSearcher fails that search call. This bug returns no wrong or partial results, corrupts nothing, and nothing persists. (On the same path a query timeout can also make the search repeat suggestions: that is the separate LFV-969.)
• How likely: plausible but uncommon. No downstream user of this path was found (code search found only copies of SuggestIndexSearcher), and no upstream test runs a CompletionQuery through IndexSearcher#search.

# Lucene main 645d4fe14a20, assertions on (-ea), seed 5EED0967: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected the suggestion 'apple' (segment 2 has no suggest field), got java.lang.NullPointerException: Cannot invoke "org.apache.lucene.search.BulkScorer.score(org.apache.lucene.search.LeafCollector, org.apache.lucene.util.Bits, int, int)" because "scorer" is null
       org.apache.lucene.search.suggest.document.TestCompletionQuerySegmentWithoutSuggestField.testSearchSkipsSegmentWithoutSuggestField(TestCompletionQuerySegmentWithoutSuggestField.java:70)
     Caused by: java.lang.NullPointerException: Cannot invoke "org.apache.lucene.search.BulkScorer.score(org.apache.lucene.search.LeafCollector, org.apache.lucene.util.Bits, int, int)" because "scorer" is null
       org.apache.lucene.search.IndexSearcher.searchLeaf(IndexSearcher.java:852)
       org.apache.lucene.search.IndexSearcher.search(IndexSearcher.java:814)
       org.apache.lucene.search.IndexSearcher.lambda$search$0(IndexSearcher.java:784)
       java.base/java.util.concurrent.FutureTask.run(FutureTask.java:328)
       org.apache.lucene.search.TaskExecutor$Task.run(TaskExecutor.java:171)
       [...]

• Contract. Weight.java:137-150: "It must return null if the scorer is null. ... @return a ScorerSupplier providing the scorer, or null if scorer is null". ScorerSupplier.java:39-46: bulkScorer() documents no null; its default is new DefaultBulkScorer(get(Long.MAX_VALUE)), and get "may not return null" (:29). The Weight#bulkScorer helper's own javadoc shows the signal: if (scorerSupplier == null) { // No docs match return null; } (Weight.java:152-179). The rule is written for the supplier: no sentence says that a non-null supplier's bulkScorer() is non-null. That follows from the default (which wraps get(), and get() may not return null), and it is what IndexSearcher#searchLeaf and TimeLimitingBulkScorer's requireNonNull rely on. The repro's fourth test checks this reading (a non-null supplier whose bulkScorer() is null), not a null get(): CompletionWeight's get() throws.
• The rule was stated when the supplier was added. In the #13319 discussion (2024), iamsanjay wrote "scorerSupplier has to be null if scorer is null", and jpountz, reviewing: "Let's return a null ScorerSupplier? Returning null from ScorerSupplier#get is not legal."
• History. In 9.12.3, CompletionWeight overrode Weight#bulkScorer and returned null in the same three cases (9.12.3 CompletionWeight.java:65-92), and IndexSearcher checked it: BulkScorer scorer = weight.bulkScorer(ctx); if (scorer != null) { (9.12.3 IndexSearcher.java:763-764). #13408 changed IndexSearcher to check only the supplier, made Weight#bulkScorer a final helper, deleted its sentence that it "can return null if this query matches no documents" (from #11897), added the requireNonNull to TimeLimitingBulkScorer, and moved CompletionWeight's three return null lines unchanged into the new ScorerSupplier#bulkScorer. CHANGES (10.0.0, CHANGES.txt:2271-2273): "Weight#bulkScorer() still exists for compatibility, but delegates to ScorerSupplier#bulkScorer()". No CHANGES or MIGRATE entry (MIGRATE.md:1678-1684, the 10.0 Weight contract notes) allows a null bulk scorer; the PR's review comments do not mention null bulk scorers or the suggester.
• Misuse is reported explicitly elsewhere in the module. CompletionScorer.java:69-72 throws IllegalArgumentException("collector is not of type TopSuggestDocsCollector"), so a generic caller with the right collector was anticipated; an NPE from core is not such a signal.
• Only direct producer. A scan of main's non-test sources for a literal return null in a ScorerSupplier#bulkScorer() body (the independent reproduction, repeated by the fact check) finds only CompletionWeight and ConstantScoreQuery (ConstantScoreQuery.java:173-176), which only forwards a null from its inner supplier.

The intended-behaviour checker and the reviews by another model family (OpenAI GPT-5.6) built the strongest case: (1) CompletionQuery.java:36 says "Use SuggestIndexSearcher#suggest(CompletionQuery, int, boolean) to execute any query that provides a concrete implementation of this query"; (2) CompletionWeight is deliberately partial (get/cost throw UnsupportedOperationException, explain returns null under a // TODO); (3) the classes are @lucene.experimental; (4) no upstream test runs a CompletionQuery through IndexSearcher#search; (5) SuggestIndexSearcher refuses an executor because the dedup logic is not thread-safe (SuggestIndexSearcher.java:41-42), and LFV-969 shows the generic path repeating hits under a timeout. So a committer could call the path unsupported.

Why it fails: line 36 recommends suggest() but forbids nothing, and IndexSearcher#search accepts any Query; SuggestIndexSearcher is an IndexSearcher, and its inherited search crashes the same way; the path (without a query timeout) worked from 8.11.4 to 9.12.3; the supplier's null rule is an explicit core contract that #13408 itself relied on when it moved IndexSearcher's check to the supplier; and the mismatch exists whatever the caller (the repro's fourth test checks it directly on each segment). The residual point, an unusual path, bears on priority and wording, not on whether it is a bug.

One fix was built and validated with gradle; one alternative was run through the standalone runner only; two were not built.

Move the three checks from the supplier's bulkScorer() into scorerSupplier() itself and return null there; bulkScorer() then only builds the CompletionScorer. One file, +28/-24. The new top of scorerSupplier:

final LeafReader reader = context.reader();
final Terms terms;
final NRTSuggester suggester;
if ((terms = reader.terms(completionQuery.getField())) == null) {
  return null;
}
if (terms instanceof CompletionTerms completionTerms) {
  if ((suggester = completionTerms.suggester()) == null) {
    // a segment can have a null suggester
    // i.e. no FST was built
    return null;
  }
} else {
  throw new IllegalArgumentException(completionQuery.getField() + " is not a SuggestField");
}
BitsProducer filter = completionQuery.getFilter();
final Bits filteredDocs;
if (filter != null) {
  filteredDocs = filter.getBits(context);
  if (filteredDocs.getClass() == Bits.MatchNoBits.class) {
    return null;
  }
} else {
  filteredDocs = null;
}

Trade-offs

• The terms lookup, suggester() and filter.getBits(context) now run in scorerSupplier(). By code reading, the two in-tree paths that take a bulk scorer from this supplier (IndexSearcher.java:842-845 and the Weight#bulkScorer helper, Weight.java:170-178, used by SuggestIndexSearcher.java:70) call bulkScorer() right after, so their work per segment, or per intra-segment partition, is the same as before; not measured. Weight.java:137-140 allows a supplier to be requested several times per segment; a caller that does so now repeats these checks, a cost that was not reviewed.
• Weight#scorer (Weight.java:129-135) also calls scorerSupplier(), then get(). With the fix it returns null for a segment that cannot match instead of throwing UnsupportedOperationException from get(); on a segment that can match it still throws that exception, now after the checks.
• The "is not a SuggestField" IllegalArgumentException moves from bulkScorer() to scorerSupplier(): IndexSearcher#search, suggest() and the Weight#bulkScorer helper throw the same exception and message as before, but Weight#scorer on such a field now throws it instead of UnsupportedOperationException. Both Weight#scorer points were checked with an executed probe on stock main and with the fix (not a regression test).
• ContextQuery's and FuzzyCompletionQuery's weights extend CompletionWeight without overriding scorerSupplier, so they get the fix too. A "Bug Fixes" CHANGES line would be usual; none is drafted.

What the checks validated

• Scratch worktree of 645d4fe14a20, gradle: the new test fails 4 of 4 on the stock tree and passes 4 of 4 with the fix, with assertions on and off; the whole lucene/suggest module (32 suites, 31 upstream plus the new one; 240 tests, 7 skipped, 0 failed; suggest.document: 62 tests, 58 of them upstream) passes with assertions on and off; :lucene:suggest:check -x test (google-java-format, ecjLint, forbiddenApis) passes.
• Standalone runner with the fix shadowed in: 4 of 4 pass (-ea, -da).
• Earlier, by the hunt: the finder's, the independent reproducer's, the refute-lens control and the adjudication's tests pass with the same fix.
• Not run: nightly tests, a benchmark.

BulkScorer scorer = null; if (scorerSupplier != null) { ...; scorer = scorerSupplier.bulkScorer(); } if (scorer != null) { ... } (+4/-1 in IndexSearcher.java).

Trade-offs

The three search tests pass, the contract test still fails. It hides contract violations of every other supplier, leaves the other consumers that use bulkScorer() without a check (LRUQueryCache.java:609, DisjunctionMaxQuery.java:166, ToParentBlockJoinQuery.java:174) exposed if a CompletionQuery is wrapped, and reverses #13408's single null signal. Not recommended.

What the checks validated

Shadowed into the stock main jars: 4 run, 1 failed (only testNoScorerSupplierWhenNothingCanMatch). Not run through gradle.

A no-op BulkScorer for a segment that cannot match.

Trade-offs

Keeps getBits in bulkScorer() and makes the supplier legal, but suggest() would then fetch a leaf collector for segments it now skips. Not built.

A javadoc note on CompletionQuery or CompletionWeight.

Trade-offs

Leaves the contract violation, and the crash in SuggestIndexSearcher's own inherited search. Not built.

Method: non-formal (the hunt's hunt unit for CompletionWeight/CompletionScorer outside SuggestIndexSearcher#suggest, 2026-10-28, main a9779ef3c193).

• Lead. A planning probe from a cross-model ideas pack printed leaf 1: supplier=non-null ... bulkScorer=ok:null without following the value further. While building the unit's differential harness for its other candidate (LFV-969), the finder read where that null goes: IndexSearcher#searchLeaf checks only the supplier.
• Reduction. A 3-test public-API JUnit (two segments, the second without the suggest field, suggest() as the oracle): 3 of 3 fail with assertions on and off, 15 of 15 over 5 iterations. A release-portable copy fixed the boundary: 9.12.3 passes, 10.0.0 fails.
• Harness context. The unit's model-based harness compared IndexSearcher#search with suggest() on 1,440 grid points for the sibling bug; suggest() was correct on all of them.