ConstKnnFloat16ValueSource accepts NaN and infinite float16 query vectors that its float32 twin rejects

ConstKnnFloat16ValueSource (lucene/queries, added with float16 vectors in #16383) returns the same float16 query vector for every document; with Float16KnnVectorFieldSource and Float16VectorSimilarityFunction inside a FunctionQuery it scores documents by exact similarity to that vector. Its constructor only null-checks the short[] (ConstKnnFloat16ValueSource.java:31-33), while its float32 twin ConstKnnFloatValueSource wraps the argument in VectorUtil.checkFinite (ConstKnnFloatValueSource.java:33) and the float16 kNN query, similarity query and field call VectorUtil.checkFiniteFloat16. So a NaN or infinite half is accepted, with assertions on and off, and reaches VectorUtil at scoring time: with -ea, EUCLIDEAN, DOT_PRODUCT and MAXIMUM_INNER_PRODUCT fail an internal assert Float.isFinite(...) and COSINE silently scores 0; with -da, documents score 0 through FunctionQuery's intended NaN/negative clamp, or +Infinity under DOT_PRODUCT and MAXIMUM_INNER_PRODUCT with an infinite component (at the default boost of 1). Float.floatToFloat16 maps any float32 of magnitude 65520 or more to infinity, so one large component is enough. It is a missing fail-fast check and a parity gap with the twin, fixed by one line, on unreleased main only (also on branch_11x); no index damage, the match set is unchanged, and no Lucene code builds the class.

• ConstKnnFloat16ValueSource (org.apache.lucene.queries.function.valuesource): "Function that returns a constant float16 vector value for every document." (ConstKnnFloat16ValueSource.java:27). Its float16VectorVal(doc) returns the stored array for every document (:40-42).
• ConstKnnFloatValueSource: the float32 twin, in the same package since #12253 (9.7.0).
• VectorUtil.checkFiniteFloat16 (VectorUtil.java:494-513): throws IllegalArgumentException when a half has all five exponent bits set, (v[i] & 0x7C00) == 0x7C00 (:507); "@throws IllegalArgumentException if any component of the vector is not finite" (:503).

1. The constructor is this.vector = Objects.requireNonNull(constVector, "constVector"); (ConstKnnFloat16ValueSource.java:31-33). Nothing checks the components.
2. The float32 twin is this.vector = VectorUtil.checkFinite(Objects.requireNonNull(constVector, "constVector")); (ConstKnnFloatValueSource.java:32-34). The two files differ only in that line, the VectorUtil import, the element type and the names.
3. checkFiniteFloat16 is called by KnnFloat16VectorQuery (:97), Float16VectorSimilarityQuery (:132) and KnnFloat16VectorField (:72, :97), not here.
4. At search time FunctionQuery.AllScorer visits every document (DocIdSetIterator.all, FunctionQuery.java:115); Float16VectorSimilarityFunction.func returns similarityFunction.compare(v1, v2) with the document's vector and the constant (Float16VectorSimilarityFunction.java:46).
5. With -ea, VectorUtil.squareDistance(short[], short[]) (EUCLIDEAN) and dotProduct(short[], short[]) (DOT_PRODUCT, MAXIMUM_INNER_PRODUCT) assert a finite result (VectorUtil.java:149, :84-91) and throw an AssertionError: with no message from squareDistance, with not finite: <result> from <a>,<b> (the raw shorts) from dotProduct; neither names the constructor argument. cosine(short[], short[]) has no such assert (:117-123).
6. With -da, FunctionQuery's score maps NaN and negative values to 0 (if (val >= 0 == false) ... return 0;, FunctionQuery.java:132-133), which is intended; a positive infinity passes the clamp and the score is boost * val (:135), so at the default boost of 1 it stays +Infinity.

Executed on main 645d4fe14a20: three documents with float16 vectors [1, 2, 3], [-1, 2, 3], [0, 2, 3]; query [h, 1, 2] with h each of the 5 non-finite halves 0x7C00 (+Infinity), 0xFC00 (-Infinity), 0x7E00, 0x7C01, 0xFFFF (NaN); default boost 1.

Float.floatToFloat16: 65504 and 65519 give 0x7BFF (65504), 65520 gives 0x7C00 (+Infinity), -100000 gives 0xFC00 (-Infinity), NaN gives 0x7E00 (OpenJDK 25.0.3). On OpenJDK 25 Lucene's vectorized code hands the float16 (short[]) kernels to the scalar implementation "until JDK 27" (PanamaVectorUtilSupport.java:310-325); the asserts sit in VectorUtil itself, above that choice.

• Who is hit. Code on main that constructs ConstKnnFloat16ValueSource from a query vector with a NaN or infinite half. No Lucene code builds the class (it appears only in its own file) and no query parser does. In the #16383 review its author said it serves the benchmark's exact-scoring path and is "not needed in production path".
• How a bad vector arises. Float.floatToFloat16 turns any float32 of magnitude 65520 or more into an infinity and keeps NaN, so a float32 query with one large component, or a NaN from an upstream normalization, is enough.
• What happens. The constructor accepts it and the failure moves to scoring: with -ea (Lucene's gradle test runs enable it for about 75% of seeds by default) an AssertionError from inside VectorUtil that does not point at the constructor argument (no message for EUCLIDEAN; not finite: ... from <raw shorts> for DOT_PRODUCT and MAXIMUM_INNER_PRODUCT); with -da (production) silent 0 scores, or +Infinity for one document under DOT_PRODUCT or MAXIMUM_INNER_PRODUCT. The same vector gets a clear IllegalArgumentException from KnnFloat16VectorQuery.
• What does not happen. No hang and no extra work (the per-document work is the same as for a finite vector), no change to which documents match (FunctionQuery matches every document), no index effect (the class is query-side only and KnnFloat16VectorField rejects non-finite halves at index time).
• Default vs opt-in, scale. Default codec and searcher suffice, but the API is opt-in and rare: float16 vectors, the @lucene.experimental FunctionQuery and a non-finite query vector. Any index size; the repro needs no index at all. Likelihood: rare.
• The same through FunctionScoreQuery. The value source can also be scored with FunctionScoreQuery through ValueSource.asDoubleValuesSource(), an adapter from 2017 (LUCENE-7610); #15329 (for #15328) made the vector-similarity value source implement doubleVal, "allowing its use in FunctionScoreQuery". FunctionScoreQuery has its own equivalent clamp: a missing, negative or NaN value scores 0 (FunctionScoreQuery.java:246-251). Executed with MatchAllDocsQuery as the inner query, the same three documents and the halves 0x7C00, 0xFC00, 0x7E00: the outcomes match the table above, with -ea and -da.

TestConstKnnFloat16ValueSourceNonFinite builds the value source from a 1-component vector holding the NaN half 0x7E00, the smallest input, and expects IllegalArgumentException, as ConstKnnFloatValueSource throws for a NaN float. Public API only; no index or directory; the seed does not matter. It compiles only where the float16 API exists (main from bfe5c847d3c). The scoring-time symptoms (the table above) follow from the accepted vector and are deliberately not asserted.

As the regression test: this same test, for example as a new method in TestKnnVectorSimilarityFunctions. With the fix it passes with assertions on and off. Its comment line is longer than 100 columns, which google-java-format flags; with the line wrapped the module's static checks pass.

cp TestConstKnnFloat16ValueSourceNonFinite.java $LUCENE/lucene/queries/src/test/org/apache/lucene/queries/function/
cd $LUCENE && ./gradlew :lucene:queries:test --tests org.apache.lucene.queries.function.TestConstKnnFloat16ValueSourceNonFinite -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off: -Ptests.asserts=false instead (same result)

TestConstKnnFloat16ValueSourceNonFinite > testNaNQueryVectorIsRejected FAILED
    junit.framework.AssertionFailedError: Expected exception IllegalArgumentException but no exception was thrown
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:8D0C32D4C80B627D]:0)
        at org.apache.lucene.tests.util.LuceneTestCaseParent.expectThrows(LuceneTestCaseParent.java:1432)
        at org.apache.lucene.tests.util.LuceneTestCaseParent.expectThrows(LuceneTestCaseParent.java:1418)
        at org.apache.lucene.queries.function.TestConstKnnFloat16ValueSourceNonFinite.testNaNQueryVectorIsRejected(TestConstKnnFloat16ValueSourceNonFinite.java:26)

# the same with -Ptests.asserts=false; with the fix: 1 test, 0 failures, assertions on and off

• The twin's check was requested in review. In #12253 uschindler wrote that ConstKnnFloatVectorValueSource "should call VectorUtil.checkFinite(vector) in its constructor to make sure the float array is finite (like the Lucene KNNQuery and Field types), so no bad thing happen", and suggested exactly today's line.
• The rule for the kNN APIs. CHANGES.txt (9.7.0): "GITHUB#12281: Require indexed KNN float vectors and query vectors to be finite." It set this for Lucene's kNN field and query APIs; it is not stated as a contract for every value source.
• The PR that added the class applied the rule to its siblings. In the #16383 review danmuzi wrote on KnnFloat16VectorQuery: "The float32 implementation validates the target vector", and that a NaN from compare() "is only caught when assertions are enabled", proposing checkFiniteFloat16; they asked for the same on KnnFloat16VectorField; both landed. On this class the author said it is "just there to be consistent with other classes ConstKnnFloatValueSource and ConstKnnByteValueSource", and msokolov replied "we may as well follow the existing pattern". Nobody discussed validation for this class.
• No sign of intent. No test covers the class or any float16 function-query class; no comment, CHANGES entry or javadoc allows non-finite input here.
• A similar parity fix. #16708 (backport #16732) closed a similar validation-parity gap: columnar addBatch skipped the Knn*VectorField checks. CHANGES.txt lists it under Improvements (10.6.0), so it is precedent for this kind of hardening, not for calling it a bug.

The strongest case for "not a bug" (the intended-behaviour devil's advocate and the cross-model "intended" review): no javadoc promises the exception (neither constructor has javadoc, and VectorSimilarityFunction.compare(short[], short[]) states no finiteness precondition); FunctionQuery is @lucene.experimental and clamps NaN to 0 on purpose; the class is a benchmark helper; and Lucene does not validate query vectors everywhere: DoubleValuesSource.similarityToQueryVector(..., short[], ...), FullPrecisionFloat16VectorSimilarityValuesSource and RescoreTopNQuery.createFullPrecisionRescorerQuery(short[]) accept a NaN query vector too (executed).

Why it fails: those three paths' float32 twins do not validate either, so they match their twins; of the four float32 classes that call VectorUtil.checkFinite (KnnFloatVectorField, KnnFloatVectorQuery, FloatVectorSimilarityQuery, ConstKnnFloatValueSource), only ConstKnnFloatValueSource has a float16 counterpart that does not validate. The twin's check was asked for in review, the class was added "to be consistent" with the twin, the same PR added checkFiniteFloat16 for exactly this input, and #12281 set the finite-vector rule for the kNN field and query APIs. Residual: a maintainer may call it hardening rather than a bug; not every other float16 entry point validates.

Option A was validated through gradle in scratch worktrees of 645d4fe14a20; B, C and D were not run.

this.vector = VectorUtil.checkFiniteFloat16(Objects.requireNonNull(constVector, "constVector")); A non-finite vector then fails at construction with IllegalArgumentException: non-finite float16 value at vector[0]=NaN (the helper's message format).

--- a/lucene/queries/src/java/org/apache/lucene/queries/function/valuesource/ConstKnnFloat16ValueSource.java
+++ b/lucene/queries/src/java/org/apache/lucene/queries/function/valuesource/ConstKnnFloat16ValueSource.java
@@ -23,13 +23,14 @@
 import org.apache.lucene.index.LeafReaderContext;
 import org.apache.lucene.queries.function.FunctionValues;
 import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.util.VectorUtil;
 
 /** Function that returns a constant float16 vector value for every document. */
 public class ConstKnnFloat16ValueSource extends ValueSource {
   private final short[] vector;
 
   public ConstKnnFloat16ValueSource(short[] constVector) {
-    this.vector = Objects.requireNonNull(constVector, "constVector");
+    this.vector = VectorUtil.checkFiniteFloat16(Objects.requireNonNull(constVector, "constVector"));
   }
 
   @Override

Trade-offs

• Parity with ConstKnnFloatValueSource, KnnFloat16VectorQuery, Float16VectorSimilarityQuery and KnnFloat16VectorField; the error names the bad component.
• Cost: one bitmask test per component, once per construction.
• Behaviour changes only for non-finite input, which no in-tree code passes.
• Like the twin, it checks once and keeps the caller's array, so later changes to that array are not caught.
• The changed line is exactly 100 columns; google-java-format accepts it.

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20, seed DEADBEEF, 2026-11-01: without the fix the repro fails with assertions on and off; with it, it passes with assertions on and off.
• With the fix, ./gradlew :lucene:queries:test --tests 'org.apache.lucene.queries.function.*': 15 classes, 112 tests, 0 failures, 0 skipped, including TestKnnVectorSimilarityFunctions (11) and the repro.
• ./gradlew :lucene:queries:check -x test with the fix and the repro as a new test file: google-java-format failed only on the repro's comment line, not on the fix, and the build stopped there, so ecj lint and forbidden APIs did not run in that run; with the line wrapped, the module's static checks pass (google-java-format, ecj lint, forbidden APIs; error-prone skipped). The full Lucene test suite was not run.
• Earlier, with the fix shadowed into the stock jars: the finder's, the independent reproducer's and the cross-model reviewers' tests pass, on ea57360912ed and 645d4fe14a20.

VectorUtil.checkFiniteFloat16(constVector.clone()) after the null check.

Trade-offs

Also guards against later changes to the caller's array (the copy question was raised in the #12253 review). Costs one allocation per construction and departs from the twin, which does not copy.

Check the vectors in Float16VectorSimilarityFunction.func.

Trade-offs

Catches any non-finite input, but costs a check per document, and document vectors are already validated at index time. Not recommended.

Say in the javadoc that non-finite components give unspecified scores.

Trade-offs

Keeps the asymmetry with the twin and with the float16 query and field. Not recommended.

• Method: twin diff, the hunt's non-formal tier, in the hunt unit on float16 vectors. Every float16 class was rewritten into its float32 twin's spelling and diffed; the ConstKnnFloat16ValueSource pair differs only in the missing VectorUtil import and checkFinite call.
• Alongside: a bounded-exhaustive check over all 65,536 half bit patterns showed that KnnFloat16VectorField, KnnFloat16VectorQuery and Float16VectorSimilarityQuery reject exactly the non-finite halves; it did not cover this class, which is why the diff found it.
• Witness: a 3-test JUnit on the stock main jar (float32-twin control, +Infinity, end-to-end EUCLIDEAN scoring) failed 2 of 3 with -ea and -da; a shadowed one-line fix made it pass.
• Later: an independent reproducer, an intended-behaviour devil's advocate, cross-model reviews and an adjudication checked it (2026-10-25); the test was reduced to one statement (2026-10-29) and re-verified on main 645d4fe14a20.