TermVectorLeafReader.getMetaData() always throws IllegalArgumentException, so a sorted search on the reader fails

TermVectorLeafReader (highlighter module, public, @lucene.experimental) wraps one document's term vectors as a one-document LeafReader. Its getMetaData() returns new LeafMetaData(Version.LATEST.major, null, null, false) (TermVectorLeafReader.java:237-240 on main 645d4fe14a20), and the LeafMetaData constructor throws IllegalArgumentException("minVersion must be set when createdVersionMajor is >= 7") for exactly that pair (LeafMetaData.java:58-60). The arguments are constants, so the method can never return. Every API that reads leaf metadata fails on the reader: a search with any Sort, Sort.RELEVANCE included (TopFieldCollector.java:58), new ParallelLeafReader(reader) (ParallelLeafReader.java:131) and IndexWriter.addIndexes(SlowCodecReaderWrapper.wrap(reader)) (IndexWriter.java:3229). Lucene's own highlighters do not ask for the reader's metadata (code reading of both in-tree call sites; their 21 term-vector tests pass), so the code that is hit is code that uses the class directly, and it gets a clean exception. The commit that added the check (LUCENE-7756, first released in 7.0.0) gave MemoryIndex's reader the valid Version.LATEST; passing the same here fixes it, and with that one-line change the repro and the whole highlighter test suite pass.

1. The reader. TermVectorLeafReader.java:237-240: return new LeafMetaData(Version.LATEST.major, null, null, false);. Version.LATEST is LUCENE_11_0_0 on main (Version.java:259), so this is created major 11 with a null minVersion.
2. The invariant. LeafMetaData is a record (LeafMetaData.java:45-46) whose compact constructor, "Expert: Sole constructor. Public for use by custom LeafReader impls." (:48-49), rejects a created major in the future (:50-53) or below 6 (:54-57), and then createdVersionMajor >= 7 && minVersion == null (:58-60). The third check always fires for this reader, whatever its document.
3. The consumers. TopFieldLeafCollector's constructor reads context.reader().getMetaData().sort() for every leaf (TopFieldCollector.java:53-59), and every IndexSearcher.search(query, n, sort) goes through it, with Sort.RELEVANCE and Sort.INDEXORDER too. ParallelLeafReader's constructor reads every sub-reader's metadata (ParallelLeafReader.java:130-131). SlowCodecReaderWrapper forwards getMetaData() (SlowCodecReaderWrapper.java:140-143), and addIndexes(CodecReader...) reads it in its up-front validateMergeReader (IndexWriter.java:3228-3229, :3288-3290).
4. The sibling that works. MemoryIndex's reader returns new LeafMetaData(Version.LATEST.major, Version.LATEST, null, false) (MemoryIndex.java:2291-2294), as does the test framework's fake reader (QueryUtils.java:312). Of the seven new LeafMetaData( calls in the non-test sources, this is the only one that passes a literal null.

The message is always "minVersion must be set when createdVersionMajor is >= 7", from LeafMetaData.<init>(LeafMetaData.java:59) via TermVectorLeafReader.getMetaData(TermVectorLeafReader.java:239).

• Who is hit. Code that constructs the reader itself (public class, public constructor) and passes it, or a FilterLeafReader that delegates metadata to it, to a metadata-reading API: a search with any Sort, new ParallelLeafReader(...), addIndexes through SlowCodecReaderWrapper, and other getMetaData() callers such as Sort.getPrimarySortField and CheckIndex (listed from code, not run). Default codec and settings; one document and one term are enough.
• Not hit: Lucene's own highlighters. The unified highlighter builds the reader and wraps it in OverlaySingleDocTermsLeafReader, a FilterLeafReader over the real segment reader whose metadata it returns (TermVectorOffsetStrategy.java:48-50, FilterLeafReader.java:477-481). The classic highlighter builds it only for term vectors with positions and offsets (WeightedSpanTermExtractor.java:393-401) and only rewrites queries and builds span weights on it. The 21 tests of TestTokenSources, TestHighlighterPhrase and TestUnifiedHighlighterTermVec pass on unfixed main; since the method throws on every call, a reached call would fail them. This rests on code reading of the two in-tree call sites plus these tests; it is not a proof for every query type or extension.
• Downstream. A code search found no use of the class in Solr, Elasticsearch or OpenSearch (not exhaustive).
• Effect. An immediate IllegalArgumentException at the call. Nothing from the reader is written: addIndexes first flushes the writer's own buffered documents, as it always does (IndexWriter.java:3286), and then its up-front validation throws before anything from the reader is added (:3288-3290). Only an Error is treated as tragic there (:3390-3392), so the writer stays open. No wrong results, no hang.
• How likely: rare. The class is a highlighter helper few applications build directly, and the documented searches found no public report since 7.0.0 (September 2017).

TestTermVectorLeafReaderSortedSearch (62 lines with the license header, one test method, package org.apache.lucene.search.highlight). ByteBuffersDirectory, a plain IndexWriterConfig(new StandardAnalyzer()), one document whose field body = "foo" stores term vectors (no positions or offsets needed). The test body makes no random calls. LuceneTestCase still randomizes the default codec, locale, time zone and similarity from the seed (SetupAndRestoreStaticEnv.java:144-230); the failure depends on none of them, and it failed with every seed tried. The catch only turns the exception into a message that states expected versus actual; a plain assertEquals(1, searcher.search(...).scoreDocs.length) that lets the exception propagate works as well.

The suggested regression test is this same test; it passes with the recommended fix.

cp $REPRO/TestTermVectorLeafReaderSortedSearch.java $LUCENE/lucene/highlighter/src/test/org/apache/lucene/search/highlight/
cd $LUCENE && ./gradlew :lucene:highlighter:test --tests TestTermVectorLeafReaderSortedSearch -Ptests.seed=DEADBEEF

# gradle, main 645d4fe14a20, -Ptests.seed=DEADBEEF (-Ptests.asserts=true; =false prints the same)
TestTermVectorLeafReaderSortedSearch > testSortedSearch FAILED
    java.lang.AssertionError: expected 1 hit from a doc-sorted search, got java.lang.IllegalArgumentException: minVersion must be set when createdVersionMajor is >= 7
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:FFA37021B6AA4628]:0)
        at org.apache.lucene.search.highlight.TestTermVectorLeafReaderSortedSearch.testSortedSearch(TestTermVectorLeafReaderSortedSearch.java:56)

        Caused by:
        java.lang.IllegalArgumentException: minVersion must be set when createdVersionMajor is >= 7
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.index.LeafMetaData.<init>(LeafMetaData.java:59)
            at org.apache.lucene.search.highlight.TermVectorLeafReader.getMetaData(TermVectorLeafReader.java:239)
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.TopFieldCollector$TopFieldLeafCollector.<init>(TopFieldCollector.java:58)
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.TopFieldCollector$SimpleFieldCollector$1.<init>(TopFieldCollector.java:200)
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.TopFieldCollector$SimpleFieldCollector.getLeafCollector(TopFieldCollector.java:199)
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.search.IndexSearcher.searchLeaf(IndexSearcher.java:836)
            ...
            at org.apache.lucene.search.highlight.TestTermVectorLeafReaderSortedSearch.testSortedSearch(TestTermVectorLeafReaderSortedSearch.java:52)

# with the recommended fix: the test passes (assertions on and off), and the whole highlighter suite passes

• Contract. LeafReader.java:526-531: public abstract LeafMetaData getMetaData(), "Return metadata about this leaf", @lucene.experimental, no throws clause. TermVectorLeafReader is a public class with a public constructor, whose javadoc reads "Wraps a Terms with a LeafReader, typically from term vectors" (TermVectorLeafReader.java:52-61), so a sorted search on it is ordinary LeafReader use. The expected behaviour follows from the abstract method and the LeafMetaData invariant; it is not stated word for word.
• History. LUCENE-7756 (23b002a0fdf, 2017) added LeafMetaData with the check, wrote this null call, and gave MemoryIndex the valid Version.LATEST in the same commit. The strict check was asked for in review (migrated issue #8807: throw "if minVersion is null but major version is >= 7"); the thread never mentions TermVectorLeafReader. That this caller was overlooked is an inference.
• No test. No test in the repository uses TermVectorLeafReader directly or expects "minVersion must be set", so no test calls this method directly.
• Context only. The LeafMetaData javadoc says minVersion may be null "if this information is not available" (LeafMetaData.java:30-31), but the constructor allows that only with created major 6 ("unknown", :27-29).

The intended-behaviour checker and the cross-model reviews built the strongest case: the class and the method are @lucene.experimental; the class is a minimal highlighter helper with stub methods (getNormValues returns null with the comment "Is this needed?", null cache helpers, empty stored fields); Lucene's own callers avoid its metadata; and DocValuesLeafReader also throws from getMetaData() (DocValuesLeafReader.java:93-95).

Why it fails: the other stubs return values their contracts allow, and none throws; DocValuesLeafReader is package-private (:25), used only inside the indexing chain and throws UnsupportedOperationException by design, whereas this is a public reader whose one metadata method trips a constructor invariant on every call; @lucene.experimental allows API change, not a method that can never succeed; and the same commit gave MemoryIndex valid metadata. The cross-model reviews rated the argument weak, and the intended-behaviour check rejected it. What it does establish is narrow reach, hence low priority.

A dissenting rating: the cross-model fact check of this doc (OpenAI GPT-5.6, read-only) rated the case moderate, not weak. Its reasons: an experimental, minimal helper; term-vector Terms that are meant to be consumed only on the thread that acquired them (TermVectors.java:26-27); little practical value in sorting a one-document reader; and DocValuesLeafReader as a reader that throws by design. It still judged the bug a real, low-priority claim, not noise, and agreed with an ordinary public issue or small PR that leads with the direct call and the sorted search.

One fix was built and validated; two alternatives were considered and not built.

One line in TermVectorLeafReader.getMetaData() (TermVectorLeafReader.java:239, 1 file, +1/-1). The reader then reports "created by and only written by this version" and no index sort, like MemoryIndex's reader (MemoryIndex.java:2293). Sorted searches and ParallelLeafReader accept it, and addIndexes gets past its metadata check (see the trade-offs).

   @Override
   public LeafMetaData getMetaData() {
-    return new LeafMetaData(Version.LATEST.major, null, null, false);
+    return new LeafMetaData(Version.LATEST.major, Version.LATEST, null, false);
   }

Trade-offs

• Version.LATEST is a convention, not recorded provenance. The constructor gets only a field name and a Terms (TermVectorLeafReader.java:61), so the reader has no version input of its own, and its term vectors may come from a segment an older version wrote. It is the convention MemoryIndex and the test framework's QueryUtils reader already use, and the created major is already Version.LATEST.major. No other trade-off is known.
• With it, addIndexes gets past validateMergeReader, which checks the created major against the index's and requires a non-null minVersion for major >= 7 (IndexWriter.java:3228-3243). The document was copied in the earlier verifiers' test, which uses SerialMergeScheduler, and in the diagram probe, a plain main() with the default IndexWriterConfig. Term-vector Terms are meant to be consumed only on the thread that acquired them (TermVectors.java:26-27), so addIndexes is a secondary path, not a general promise.
• An upstream test of the addIndexes path (not part of the repro) should use SerialMergeScheduler: with the fix, the test framework's AssertingTerms rejected the Terms being consumed on a ConcurrentMergeScheduler thread in the first fixed run of the cross-model reviews.

What the checks validated

• Scratch worktree of 645d4fe14a20, gradle --no-daemon, OpenJDK 25.0.3, seed DEADBEEF: the repro test fails on the stock tree with assertions on and off, and passes with the fix with assertions on and off.
• With the fix, :lucene:highlighter:test with assertions on: 35 suites (the repro included), 723 tests, 0 failures, 0 errors.
• :lucene:highlighter:checkGoogleJavaFormat passes with the fix and the test in the tree.
• Earlier, on main a9779ef3c193: the finder's, the independent reproduction's, the cross-model review's and the intended-behaviour check's own tests all pass with the same change shadowed (the independent reproduction 6 of 6 covering the direct call, ParallelLeafReader, INDEXORDER-sorted search and addIndexes).

The LeafMetaData javadoc treats created major 6 as "unknown" (LeafMetaData.java:27-29), and the constructor accepts it with a null minVersion. Not built.

Trade-offs

addIndexes would then reject the reader: validateMergeReader throws when the index's created major differs from the reader's (IndexWriter.java:3230-3236). So it trades one exception for another on that path.

Allow a null minVersion for created major >= 7, as the javadoc wording "or null if this information is not available" suggests (LeafMetaData.java:30-31). Not built.

Trade-offs

Broader and against the review that asked for the strict check; IndexWriter.java:3238-3242 separately rejects a null minVersion for created major >= 7 ("hides it"), so addIndexes would still fail.

Method: non-formal (code reading plus execution; the hunt's hunt unit for ParallelLeafReader "as if one index" metamorphic checks, 2026-10-27, main a9779ef3c193).

• Reader sweep. One leg of the plan wrapped each public LeafReader type as a ParallelLeafReader sub-reader: SegmentReader, the soft-deletes and exitable leaves, SlowCodecReaderWrapper, SortingCodecReader, FieldFilterLeafReader, MemoryIndex's reader and TermVectorLeafReader, each with construct, identity-dump and addIndexes-copy checks, with assertions on and off. Only TermVectorLeafReader failed, at construction, with the minVersion exception.
• Reduction. The lead from the plan's code reading was reduced to a public-API JUnit (direct getMetaData(), then ParallelLeafReader and a sorted search), and later minimized to the one-method sorted-search test shown above.