CheckIndex silently skips FLOAT16 vector fields: it reports "OK [0 fields, 0 vectors]" and never runs checkFloat16VectorValues

On main, CheckIndex.testVectors skips a vector field when both getFloatVectorValues and getByteVectorValues return null (CheckIndex.java:2864-2867 at 645d4fe14a20). CodecReader's final getters return null for any field whose encoding is not FLOAT32 or BYTE respectively, so every FLOAT16 field (KnnFloat16VectorField, new in the unreleased 11.0 with #16383; on main and branch_11x) is skipped before it is counted: CheckIndex at level 2 or higher prints test: vectors.............OK [0 fields, 0 vectors] for an index with one FLOAT16 vector, while the same index with a FLOAT32 vector gives OK [1 fields, 1 vectors]. The FLOAT16 arm of the switch and the dedicated checkFloat16VectorValues (kNN self-search, dimension and size checks), added by the same commit, can never run. Lucene's randomized vector-format tests index FLOAT16 vectors and run CheckIndex on close, but a skipped field raises no error. File checksums and, on HNSW formats such as the default codec, the encoding-agnostic HNSW graph check still run, and indexing and search are not affected. The fix is one more term in the guard, the same widening #12064 made when byte vectors got their own getter.

1. checkIndex runs testVectors only at level >= Level.MIN_LEVEL_FOR_INTEGRITY_CHECKS = 2 (CheckIndex.java:1114, :1141, :4754). The command-line default is level 1, "Checksum checks only" (:4748, :4837).
2. For each field with vector values, testVectors does:

if (reader.getFloatVectorValues(fieldInfo.name) == null
    && reader.getByteVectorValues(fieldInfo.name) == null) {
  continue;
}
status.totalKnnVectorFields++;
switch (fieldInfo.getVectorEncoding()) {
  case BYTE:    checkByteVectorValues(...);
  case FLOAT16: checkFloat16VectorValues(...);
  case FLOAT32: checkFloatVectorValues(...);

(CheckIndex.java:2864-2898, abridged; the FLOAT16 arm is :2878-2884.)

1. CodecReader.getFloatVectorValues and getByteVectorValues are final and return null unless the field's encoding is FLOAT32 or BYTE respectively (CodecReader.java:235-252, :255-265). Only getFloat16VectorValues returns values for a FLOAT16 field (:269-279).
2. So for a FLOAT16 field the loop takes continue before the counter (CheckIndex.java:2869) and before the switch. testVectors takes a CodecReader and the getters are final, so checkFloat16VectorValues (:3164-3213) cannot run for any reader. The summary line prints both counters: OK [0 fields, 0 vectors] (:2902-2909).

• Still runs: file checksums (level 1 and up) and testHnswGraphs (CheckIndex.java:2926-2945), which loops over every vector field whatever its encoding and checks the graph of each field whose reader is an HnswGraphProvider (:2937-2944), as with the default codec; the probe shows hnsw graphs ... OK [1 fields] for the FLOAT16 index.
• Lost for FLOAT16 fields: what checkFloat16VectorValues does, the same checks FLOAT32 and BYTE fields get: it reads every vector by ordinal and checks its length against the field's dimension; for each vector whose document id is a multiple of max(size/64, 1) (every vector, for fields with fewer than 128) it runs a k=10 kNN search that must return a hit (when the format supports search); and it checks that the number of vectors read equals size(). Plus correct field and vector counts.

One document, one 2-dimension EUCLIDEAN vector [1, 2], default codec, CheckIndex <dir> -level 2 on the stock jar of 645d4fe14a20:

The finder's test and the verifiers saw the same on larger indexes: a 2-field, 3-vector FLOAT16 index reports 0 fields / 0 vectors, and a segment with a FLOAT32 (7 vectors), a BYTE (5) and a FLOAT16 (11) field reports OK [2 fields, 12 vectors]: only the FLOAT16 field is missing.

• Who is hit. Main and branch_11x (FLOAT16 vectors are unreleased, 11.0.0). Default codec, any index size, any similarity. CheckIndex at level 2 or 3: the API with setLevel, the command line with -level 2/3, TestUtil.checkIndex(Directory) (level 3, TestUtil.java:302-303) and the test framework's check-on-close (level 3, or 2 without slow checks; BaseDirectoryWrapper.java:32-33, :44-45, :64-70). The command-line default, level 1, checks only checksums for every encoding.
• Deterministic. Every FLOAT16 field is skipped, every time: over 10 random-seed iterations every FLOAT16 test failed and every FLOAT32/BYTE control passed.
• CheckIndex's part of Lucene's test net. Lucene tests FLOAT16 reading, search and graphs directly (for example TestHnswFloat16VectorGraph, TestFloat16VectorSimilarityQuery). What misses FLOAT16 is the CheckIndex layer: BaseKnnVectorsFormatTestCase draws the vector encoding at random per test, FLOAT16 included (BaseKnnVectorsFormatTestCase.java:128, :147-157, :1351), and the indexes its tests make with newDirectory() are checked on close. With the bug, a FLOAT16 defect that only CheckIndex would catch (wrong dimension, missing or unsearchable vectors) passes that check. FLOAT16 is new code still being completed (tracker #16725), which is where such checks matter most.
• Default vs opt-in. The codec is the default; the experimental field type (KnnFloat16VectorField is @lucene.experimental) and CheckIndex level 2 or higher are the opt-ins.
• Not affected. Indexing, search hits, scores, live docs and stored data. File checksums and, on HNSW formats such as the default codec, the HNSW graph check still run for FLOAT16 fields.

KnnFloat16VectorField, IndexWriter, CheckIndex.setLevel and CheckIndex.Status, plus Lucene's test framework (LuceneTestCase, TestUtil), so it lives in Lucene's test tree; no package-private members; the default codec is pinned with TestUtil.getDefaultCodec() because the test framework otherwise randomizes it; ByteBuffersDirectory. Copy the file into lucene/core/src/test/org/apache/lucene/index/ and run the command; the same result with -Ptests.asserts=false.

Regression test: this same test; it passes with the fix and fits as one more method in TestCheckIndex.

cp $REPRO/TestCheckIndexFloat16Vectors.java $LUCENE/lucene/core/src/test/org/apache/lucene/index/
cd $LUCENE && ./gradlew :lucene:core:test --tests TestCheckIndexFloat16Vectors -Ptests.seed=DEADBEEF
# the same result with -Ptests.asserts=false

# gradle, stock 645d4fe14a20, -Ptests.seed=DEADBEEF (assertions on; the same with -Ptests.asserts=false)
TestCheckIndexFloat16Vectors > testFloat16VectorFieldIsChecked FAILED
    java.lang.AssertionError: vector fields checked expected:<1> but was:<0>
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:77A3C607A3646CF3]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.failNotEquals(Assert.java:835)
        at org.junit.Assert.assertEquals(Assert.java:647)
        at org.apache.lucene.index.TestCheckIndexFloat16Vectors.testFloat16VectorFieldIsChecked(TestCheckIndexFloat16Vectors.java:42)

# with the recommended fix: 1 test, 0 failures (assertions on and off)

# the same one-vector index through the command line, CheckIndex <dir> -level 2, stock jar:
    test: field infos.........OK [1 fields] [took 0.000 sec]
    test: vectors.............OK [0 fields, 0 vectors] [took 0.000 sec]
    test: hnsw graphs.........OK [1 fields] [took 0.002 sec]
No problems were detected with this index.
# with the fix: test: vectors.............OK [1 fields, 1 vectors]

• A checker that cannot run. git log -S 'checkFloat16VectorValues' and git log -S 'case FLOAT16:' on CheckIndex.java return only #16383 (bfe5c847d3c). Nobody writes a checker in order never to call it.
• Precedent in the same guard. #12064 (cc29102a24a, 2023) gave byte vectors their own field and getter (KnnByteVectorField, getByteVectorValues; byte-encoded vectors themselves date from LUCENE-10577, released in 9.4.0), made the getters return null on an encoding mismatch, and widened this guard from one getter to two in the same change.
• Contract text. totalKnnVectorFields: "Total number of fields with vectors" (CheckIndex.java:420-421). Level 2: "All level 1 checks + logical integrity checks" (:4838). LeafReader.getFloat16VectorValues returns values "or null if no Float16VectorValues were indexed" (LeafReader.java:237-243), the same contract as the other getters. MIGRATE.md's #16383 section: "exhaustive VectorEncoding switches need a FLOAT16 arm" (MIGRATE.md:629-645); CheckIndex's switch did get that arm and the omission is the null guard in front of it, so this supports "every encoding dispatch must handle FLOAT16" rather than naming this guard.
• Tests. testCheckIndexIncludesVectors (BaseKnnVectorsFormatTestCase.java:1947-1976: "Make sure CheckIndex in fact declares that it is testing vectors!") and TestCheckIndex.java:203-207 assert the vector counts, for KnnFloatVectorField only. No test, javadoc, CHANGES or MIGRATE entry says CheckIndex excludes FLOAT16.
• History. None of the 101 texts of the #16383 thread mentions CheckIndex; the earlier, unmerged fp16 PR #15549 had the identical CheckIndex hunk without the guard term.

The strongest case for "intended": FLOAT16 is unreleased and @lucene.experimental, and so is CheckIndex itself (CheckIndex.java:110); the fp16 work is openly incomplete (tracker #16725 says "there might be more" missing places); the guard is old and deliberate (it skips fields the codec has no values for); nothing is corrupted or mis-searched; and the call-site comment still reads "// Test FloatVectorValues and ByteVectorValues" (:1140).

Why it fails: every point is about impact or timing, not intent. The same commit wrote the FLOAT16 checker, so the skip is an omission. The guard's purpose, skipping fields with no values, is kept by the fix, since getFloat16VectorValues returns null exactly when no FLOAT16 values exist. The comment is pre-FLOAT16 text, not a design statement. The cross-model reviews rated the intended argument weak; a later cross-model fact check agreed, calling it moderate only as a triage argument (maintainers may fold it into the incomplete fp16 work of #16725 at low priority). Verdict: not intended, a defect of low severity.

One option was built and validated; the alternative makes the compiler catch the next new encoding.

One term in CheckIndex.testVectors (CheckIndex.java:2864-2867), +2/-1. Optionally also update the stale call-site comment at :1140 ("Test FloatVectorValues and ByteVectorValues"); comment only, not part of the validated diff.

if (reader.getFloatVectorValues(fieldInfo.name) == null
    && reader.getByteVectorValues(fieldInfo.name) == null
    && reader.getFloat16VectorValues(fieldInfo.name) == null) {
  continue;
}

Trade-offs

• Cost. Not benchmarked. The re-enabled checker has the same shape as the FLOAT32 and BYTE ones (one pass over the vectors plus sampled searches), so a level-2 check of a FLOAT16 field is expected to cost about what a FLOAT32 field costs.
• Side effect, intended. The checker now runs in every test that closes a FLOAT16 index, so randomized runs could surface latent FLOAT16 codec bugs; the suites below found none.

What the checks validated

Applied to a scratch worktree of 645d4fe14a20 and run through gradle with OpenJDK 25.0.3, seed DEADBEEF (2026-10-31; an independent fact check re-ran the stock and fixed gradle runs, assertions on and off):

• stock: the minimal test fails with assertions on and off;
• with the fix: the minimal test passes with assertions on and off;
• the command-line probe prints OK [1 fields, 1 vectors] for the one-vector FLOAT16 index (unchanged OK [1 fields, 1 vectors] for FLOAT32);
• the closest suites pass: TestCheckIndex (9 tests), every core vector-format suite (lucene99.*, lucene104.*, TestPerFieldKnnVectorsFormat) and the FLOAT16 query and HNSW graph tests (21 classes with the other tests the package globs picked up, such as TestForUtil: 509 tests, 0 failures); TestSimpleTextKnnVectorsFormat and the sandbox TestDedupHnswVectorsFormat, 57 tests each, 0 failures. These suites draw the encoding at random per test, FLOAT16 included, and check the indexes they make with newDirectory() on close. Core lint (checkGoogleJavaFormat, ecjLintMain, forbiddenApisMain) passes;
• earlier: the finder's sweep of 396 indexes (11 stock vector formats and encodings x 4 similarities x dimensions 3, 64, 1024 x 3 index shapes) was clean with the fix while the stock jar failed at the first index, and the verifiers' and the cross-model reviewers' own tests passed with it.

Fetch the values once with a switch expression on fieldInfo.getVectorEncoding() (BYTE -> getByteVectorValues, FLOAT16 -> getFloat16VectorValues, FLOAT32 -> getFloatVectorValues) and skip when the result is null.

Trade-offs

A switch expression over an enum must be exhaustive, so without a default arm javac forces whoever adds a fourth encoding to handle it, the omission that happened here (a classic switch statement would not). A larger diff with the same behaviour as the first option today.

Method: non-formal, code reading followed by an executed test (hunt unit on fp16 vectors, 2026-10-25, main ea57360912ed).

• The finder enumerated every reader and codec dispatch site on VectorEncoding with grep and checked each for a FLOAT16 arm. CheckIndex.testVectors has one, but the guard in front of it tests only getFloatVectorValues and getByteVectorValues.
• It wrote the FLOAT16 twin of the upstream BaseKnnVectorsFormatTestCase#testCheckIndexIncludesVectors (2 documents, 2 fields, 3 vectors) next to a FLOAT32 control. On the stock jar the FLOAT16 test failed with OK [0 fields, 0 vectors] expected:<3> but was:<0>, with assertions on and off; the control passed.
• The one-term fix made it pass, and a 396-index sweep over the stock vector formats found no false positive with the fix.
• A later minimization reduced it to the one-document test shown here (2026-10-29).