IndexSearcher rejects any reader that contains an empty leaf

Since 10.0.0 IndexSearcher's own slicing wraps every leaf of its reader in a LeafReaderContextPartition, a leaf plus a doc-id range; a whole leaf gets [0, NO_MORE_DOCS) from createForEntireSegment. The partition constructor throws IllegalArgumentException when minDocId >= leaf.maxDoc(), a check that intra-segment concurrency (#13542) added to the partition constructor at a reviewer's request. It runs for the whole-leaf partition too, and for a leaf with maxDoc() == 0 it reads 0 >= 0. So a reader that contains an empty leaf cannot be searched: new IndexSearcher(new ParallelLeafReader(true)) throws where 9.12.3 counts 0, and a MultiReader of a 5-document index plus that leaf throws where 9.12.3 finds 5. A reader with no leaves at all is special-cased and works. Indexes that IndexWriter writes never contain an empty leaf, so in practice only readers assembled in memory hit it. Every release from 10.0.0 to 10.6.0 and main is affected; 9.x is not.

1. new IndexSearcher(reader) (:189-191) delegates to IndexSearcher(IndexReaderContext, Executor) (:218-232). Without an executor it builds its one slice at once: leafContexts.isEmpty() ? new LeafSlice[0] : new LeafSlice[] {LeafSlice.entireSegments(leafContexts)} (:226-231). A reader with no leaves is special-cased; a leaf with no documents is not.
2. LeafSlice.entireSegments wraps every leaf with LeafReaderContextPartition.createForEntireSegment(ctx) (:1021-1028).
3. createForEntireSegment always passes minDocId 0 and maxDocId DocIdSetIterator.NO_MORE_DOCS (:1097-1100).
4. The private constructor (:1068-1094) checks minDocId >= maxDocId, minDocId < 0 and minDocId >= leafReaderContext.reader().maxDoc() (:1081-1088). For an empty leaf the third reads 0 >= 0 and throws "minDocId is greater than than maxDoc: [0] > [0]" (the message says >; the check is >=).
5. Every other stock slicing path reaches the same constructor: executor searchers lazily through getSlices() and computeAndCacheSlices() (:537-543, :545-565) on the first count() or search(), and the public static slices(leaves, maxDocsPerSlice, maxSegmentsPerSlice, allowSegmentPartitions) (:341-390) with partitions off (:385) and on (:422; an empty leaf always fits in a slice).

Before #13542 a slice held plain leaves and nothing was checked per leaf, so 9.x searched the empty leaf and found nothing in it.

ParallelLeafReader's constructor accepts zero readers and then sets this.maxDoc = this.numDocs = 0 (ParallelLeafReader.java:96-98). Any custom LeafReader whose maxDoc() is 0 does the same. Wrapping it, nesting it or putting it in a MultiReader next to real indexes does not help: every leaf is wrapped.

On 10.0.0 the no-executor constructor still computed slices lazily, so the first count() or search() throws; from 10.1.0 (#13893) the constructor throws, and from 10.2.0 (#14343) through LeafSlice.entireSegments. With an executor it throws from getSlices() in every affected version.

• Who is hit: applications that assemble a reader in memory with an empty leaf. One empty leaf makes the whole MultiReader unsearchable, its non-empty leaves included.
• Default vs opt-in: the default IndexSearcher, no setting involved; what is opt-in is the reader composition.
• Scale: none; one empty leaf is enough and no index is needed.
• Severity: a loud, deterministic IllegalArgumentException on every attempt. Nothing is persisted, no wrong result is ever returned, nothing hangs and no search task is submitted (executed probe).
• Not hit: readers over indexes that IndexWriter wrote. IndexWriter never writes a 0-doc segment (LUCENE-5173: "Lucene never writes segments with 0 documents anymore", lucene/CHANGES.txt:13437), and CheckIndex rejects one (CheckIndex.java:1011-1013). A hand-written 0-doc segment does open (a fact-check probe: DirectoryReader.open gives one leaf with maxDoc() 0 and IndexSearcher throws the same exception), but CheckIndex rejects it as illegal and index files are trusted input (SECURITY.md:30-34). A fully hard-deleted segment kept by the merge policy, a fully soft-deleted segment (SoftDeletesDirectoryReaderWrapper drops the leaf) and a FilterDirectoryReader that hides every document through live docs all keep maxDoc() > 0 and search fine (executed). A ParallelCompositeReader with no readers has no leaves; MemoryIndex and TermVectorLeafReader report maxDoc() 1.
• Downstream: a read-only code search found no readerless ParallelLeafReader in Elasticsearch, OpenSearch or Solr; Solr's one ParallelLeafReader always has inputs and feeds a merge. A spot check, not proof.
• Exposure so far: 13 releases over two years (10.0.0 to 10.6.0) and no report found.
• Workaround: leave zero-doc leaves out of the reader. Overriding the protected slices(List) cannot help the no-executor constructor, which builds its slice directly (IndexSearcher.java:226-231).

Copy the class into lucene/core/src/test/org/apache/lucene/search/ of a checkout and run it with gradle; it needs only core and the test framework. It fails the same way with assertions off (-Ptests.asserts=false). The same class is the suggested regression test: it fails on stock main through gradle and passes with either fix.

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF (trimmed)
TestSearchZeroDocLeaf > testCountOnEmptyParallelLeafReader FAILED
    java.lang.AssertionError: expected count 0 for a maxDoc() == 0 leaf, but threw java.lang.IllegalArgumentException: minDocId is greater than than maxDoc: [0] > [0]
        at org.apache.lucene.search.TestSearchZeroDocLeaf.testCountOnEmptyParallelLeafReader(TestSearchZeroDocLeaf.java:31)
        Caused by:
        java.lang.IllegalArgumentException: minDocId is greater than than maxDoc: [0] > [0]
            at org.apache.lucene.search.IndexSearcher$LeafReaderContextPartition.<init>(IndexSearcher.java:1086)
            at org.apache.lucene.search.IndexSearcher$LeafReaderContextPartition.createForEntireSegment(IndexSearcher.java:1099)
            at org.apache.lucene.search.IndexSearcher$LeafSlice.entireSegments(IndexSearcher.java:1025)
            at org.apache.lucene.search.IndexSearcher.<init>(IndexSearcher.java:230)
            at org.apache.lucene.search.IndexSearcher.<init>(IndexSearcher.java:202)
            at org.apache.lucene.search.IndexSearcher.<init>(IndexSearcher.java:190)
            at org.apache.lucene.search.TestSearchZeroDocLeaf.testCountOnEmptyParallelLeafReader(TestSearchZeroDocLeaf.java:28)
:lucene:core:test (FAILURE): 1 test, 1  failure

# standalone runner, seed DEADBEEF (summary of the runs)
main 645d4fe14a20  -ea: FAIL 1/1   -da: FAIL 1/1
10.6.0             -ea: FAIL 1/1
10.0.0             -ea: FAIL 1/1   (the constructor succeeds; count() throws from getSlices())
9.12.3             -ea: pass 1/1

The contract is implied, not stated outright.

• IndexSearcher(IndexReader): "Creates a searcher searching the provided index." (IndexSearcher.java:188-191): no precondition, not @lucene.experimental.
• IndexReader#maxDoc: "Returns one greater than the largest possible document number." (IndexReader.java:300-305): no lower bound.
• LeafReader: "Search of an index is done entirely through this abstract interface, so that any subclass which implements it is searchable." (LeafReader.java:31-34)
• ParallelLeafReader handles zero sub-readers on purpose (ParallelLeafReader.java:96-98); the upstream test TestParallelReaderEmptyIndex builds one (:49-50, LUCENE-1918), though only for addIndexes.
• IndexSearcher special-cases a reader with no leaves (IndexSearcher.java:227-229).
• 9.12.3 searches these readers correctly (executed). The 10.0.0 CHANGES entry for #13542 (lucene/CHANGES.txt:2332) and MIGRATE's six #13542 items say nothing about empty leaves, and no upstream test asserts the rejection.

History of the check. In the #13542 review jpountz asked (2024-07-31, on the private constructor that both factories share): "Can you add validation, e.g. minDocId >= 0, maxDocId > minDocId, minDocId < context.reader().maxDoc(), etc?", and javanna answered (2024-08-26) "good with the proposed validation", keeping NO_MORE_DOCS as the upper bound when targeting the entire segment. None of the PR's 30 comments, 99 review comments and 77 reviews mentions empty or 0-doc leaves.

Precedent. LUCENE-5045 (#6109, 2013): DrillSideways threw IllegalArgumentException on an empty reader; the report says "there's nothing technically wrong from running a search against an empty index", and it was fixed as a bug. In #15803 (2026-03-10) mikemccand wrote "Lucene tries hard to never produce a 0-doc segment" and still asked for an explicit test with 0-doc segments.

The strongest case for "intended" (rated moderate by the cross-model reviewers, weak to moderate by the devil's-advocate verifier): the check is deliberate and is literally what the reviewer asked for ("minDocId < context.reader().maxDoc()"); LeafReaderContextPartition is @lucene.experimental; and Lucene never writes 0-doc segments (LUCENE-5173; CheckIndex rejects maxDoc <= 0), so an empty leaf is an unusual, synthetic reader.

Why it fails: the failure surfaces through the stable IndexSearcher(IndexReader) constructor, not the experimental partition API; the review was about partition bounds, and nobody discussed what the check does to the whole-leaf partition of an empty leaf; LUCENE-5173 and CheckIndex govern segments written to disk, while ParallelLeafReader is a public reader that handles zero inputs on purpose; and a fix that keeps the validation for real partitions leaves search working, with 0 hits in the empty leaf and correct counts beside it. That the effect on the empty whole-leaf partition was overlooked is an inference, not something the PR says. Verdict: not intended; rare.

Two fixes were built and validated; for every partition Lucene itself creates on today's main they behave the same. C is recommended because it does not depend on how the whole-leaf range is represented, which open PR #16952 changes.

The change is +21/-20 lines in IndexSearcher.java: the three checks move, unchanged, from the private LeafReaderContextPartition constructor into createFromAndTo, the only factory that takes caller-supplied bounds. createForEntireSegment passes no check, because its range is the whole leaf, whatever the leaf's size.

public static LeafReaderContextPartition createFromAndTo(
    LeafReaderContext ctx, int minDocId, int maxDocId) {
  assert maxDocId != DocIdSetIterator.NO_MORE_DOCS;
  // only a true partition needs a range check: the entire-segment partition is valid for any
  // leaf, including one with no documents
  if (minDocId >= maxDocId) { throw ... }            // moved from the constructor, unchanged
  if (minDocId < 0) { throw ... }                    // moved, unchanged
  if (minDocId >= ctx.reader().maxDoc()) { throw ... } // moved, unchanged
  return new LeafReaderContextPartition(ctx, minDocId, maxDocId, maxDocId - minDocId);
}

Trade-offs

• True partitions keep exactly the same checks and messages; only the whole-leaf partition, whose bounds the code chooses itself, is no longer checked.
• It survives #16952 (open, opened 2026-10-30), which makes createForEntireSegment pass (0, maxDoc): there an empty leaf would otherwise fail the first check (0 >= 0).
• It moves about 20 lines, so it conflicts textually with draft #16847, which edits the third check.
• No behaviour change for any leaf with at least one document.

What the checks validated

Gradle in a scratch worktree of 645d4fe14a20, OpenJDK 25.0.3, seed DEADBEEF (2026-10-31). Stock: the minimal test fails with assertions on and off. With C:

• the minimal test plus TestIndexSearcher, TestTaskExecutor, TestTotalHitCountCollector, TestTopFieldCollectorEarlyTermination, TestSegmentToThreadMapping, TestForTooMuchCloning, TestParallelLeafReader, TestParallelReaderEmptyIndex and TestParallelCompositeReader: 10 classes, 65 tests, 0 failures, 1 skipped, with assertions on and off;
• core lint (checkGoogleJavaFormat, ecjLintMain, ecjLintTest, forbiddenApisMain, forbiddenApisTest) passes with the test in place;
• with open PR #16952 applied as well: the same run plus a verifier's sequential and executor search(q, 10) tests passes (11 classes, 70 tests, 0 failures, 1 skipped), while the minimal test alone fails on #16952 without a fix.

With the patched IndexSearcher.java shadowed on main's jars: the finder's 3 tests (the empty leaf alone and next to a 5-doc index), a verifier's 7 tests (sequential, executor and static slices(); 5 of 7 fail on stock) with assertions on and off, and another verifier's executor/static test (4/4) all pass. The whole org.apache.lucene.search package was run with A only.

The change is +3/-1 lines in IndexSearcher.java: the hunt's one-condition fix.

// the whole-segment partition (0, NO_MORE_DOCS) is also valid for a leaf with no documents
if (minDocId >= leafReaderContext.reader().maxDoc()
    && (minDocId != 0 || maxDocId != DocIdSetIterator.NO_MORE_DOCS)) {

Trade-offs

• One condition, the smallest change; for every partition Lucene itself creates on today's main it behaves exactly like C (they differ only for a direct createFromAndTo(ctx, 0, NO_MORE_DOCS) call on a 0-doc leaf with assertions off, which A accepts and C rejects).
• It keys on the NO_MORE_DOCS sentinel, so it stops working if open PR #16952 is merged: with #16952 applied, the minimal test fails with A on top (minDocId is greater than or equal to maxDocId: [0] > [0]).

What the checks validated

Gradle in the same scratch worktree of 645d4fe14a20: the minimal test passes with assertions on and off; the minimal test plus the suites listed under C: 10 classes, 65 tests, 0 failures, 1 skipped; the whole org.apache.lucene.search package: 215 classes, 2,340 tests, 0 failures, 49 skipped; core lint passes with the test in place.

Earlier, in the hunt: every repro (the finder's 3, the verifiers' 7 and 7, the adjudication's re-run 5), 10.0.0 and the introducing commit with it applied, the bounded-exhaustive harness (0 failures) and TestIndexSearcher, TestCachingCollector(Manager), TestMultiCollector(Manager) and TestDocValuesStatsCollector.

Leave leaves with maxDoc() == 0 out of LeafSlice.entireSegments and slices(...).

Trade-offs

Collectors would never see the leaf, the slices would no longer cover every leaf of the reader, and the public static slices() would return different slices. A reader whose only leaf is empty would get no slice at all, and search() asserts leafContexts.isEmpty() in that case (IndexSearcher.java:764), so that would need changing too. More invasive than C for no gain.

Method: bounded-exhaustive translation validation (the hunt's semi-formal tier) of the public static IndexSearcher.slices(leaves, maxDocsPerSlice, maxSegmentsPerSlice, allowSegmentPartitions) in a hunt on concurrent collector managers and slicing, run on the real main jar (ea57360912ed).

• A harness enumerated 1-3 leaves of 0-10 documents, every maxDocsPerSlice and maxSegmentsPerSlice up to the bound, partitions off and on, plus a few shapes near IndexWriter.MAX_DOCS, and checked properties P0-P6 on the result.
• P0, "slices() does not throw for a legal reader", failed in 31,176 of 178,996 configurations, which is exactly the number of enumerated configurations that contain a 0-doc leaf (recomputed from the harness loops); 116,100 of 1,013,068 in a 3 x 0..16 run.
• The partition properties P1-P6 held in all 5,894,928 configurations of 1-4 leaves with 1-12 documents (23,834,568 in a 4 x 1..16 run); z3 discharged the partition arithmetic obligations; the variant with the fix had 0 failures.
• The finder then reduced it by hand to a 3-test public-API JUnit on the stock jars; the hunt later cut that to the one-method test shown here.