IndexWriter#addBatch: a dense points column that fails after its first chunk gives later documents the rejected values

IndexWriter#addBatch copies a dense points column (a LongColumn with points, or a BinaryColumn with point dimensions) into the field's in-memory points buffer one 4 KiB chunk at a time, and counts the copied points only after the last chunk. If the batch fails after the first chunk, because the application's cursor throws or because Lucene's own width check rejects a value, Lucene rejects the batch as a non-aborting failure and keeps the writer open, but the copied bytes stay in the buffer uncounted. Every later point of that field in the same in-memory segment is then read back with the value written k places earlier (k = the values left behind; with one point per document, the first k later documents get the rejected batch's values): in the repro, 3 documents added with p = 7, 8, 9 after a rejected 1025-value batch read back 1000, 1001, 1002. Nothing reports it: CheckIndex is clean and merges keep the wrong values. The same failure inside the first chunk leaves no point bytes behind, and the later documents keep their values. It shipped with the experimental column API in 10.5.0.

• Column API. IndexWriter#addBatch(ColumnBatch) (@lucene.experimental, since 10.5.0) indexes a batch of documents field by field instead of document by document. A dense column has one value per document of the batch and hands its values over through a values cursor (LongValuesCursor, BytesRefValuesCursor).
• Points buffer. While a segment is in memory, PointValuesWriter keeps, per points field, the packed point bytes in one append-only buffer and the doc ID of each point in a parallel array; point i of the buffer belongs to doc ID i of the array. numPoints says how many entries are valid.
• Non-aborting exception. A failure that only rejects the current document or batch: its documents are marked deleted and the in-memory segment stays in use. The DocumentsWriter javadoc promises that the partial updates such a failure leaves "are consistent".

1. A dense LongColumn with points goes to addDense1DIntValues or addDense1DLongValues, a dense BinaryColumn with point dimensions to addDenseNDValues (IndexingChain.java:1094-1103, :1215-1220).
2. Each method writes the batch's doc IDs into the array (reserveDenseRange, :173-185) but leaves numPoints unchanged.
3. Its loop fills one chunk from the cursor and appends it to the buffer at once (fillIntPoints then bytesOut.writeBytes, :113-118; long :131-136; N-D :150-155). A chunk is the 4 KiB shared scratch (SharedIndexingScratch.java:33): 1024 ints, 512 longs or 4096/width N-D values.
4. Only after the loop does commitDenseRange advance numPoints, numDocs and lastDocID and count the bytes in the RAM counter (:187-192). There is no try/finally.
5. The cursor throws while filling chunk 2: the application's cursor fails, or Lucene's default BytesRefValuesCursor#fillPackedPoints, which "validates each length", throws IllegalArgumentException: dense point value has length=3 but should be 4 (BytesRefValuesCursor.java:67-80). The 1024 values of chunk 1 stay in the buffer; numPoints is still 0.
6. DocumentsWriterPerThread.updateBatch treats it as non-aborting: it marks the 1025 documents deleted and keeps the in-memory segment (DocumentsWriterPerThread.java:342-355).
7. The next document with p = 7 appends its 4 bytes after the 1024 orphaned values (:93) but records its doc ID at array position numPoints = 0 (:95). At flush, point i gets doc docIDs[i] and the bytes at offset i × 4 (:242-250): the new document gets 1000, the next ones 1001 and 1002, and the bytes of 7, 8 and 9 are never read.

With k orphaned values, the j-th later point of the field reads the value at buffer position j: the first k later points get the rejected batch's values in order (the first k later documents, with one point per document as in the repro), later ones the value of the point k earlier; a second rejected batch before the flush adds its own left-over values, so k grows (read from the code, not executed). In the repro k = 1024 and 3 documents follow: [7, 8, 9] reads back as [1000, 1001, 1002]. The threshold is one value more than a chunk: 1025 int, 513 long or 4096/width + 1 N-D values. Points indexed before the failed batch are unaffected, and the damage ends when the segment flushes. Side effect: the orphaned bytes are missing from the RAM counter until that flush (a probe with 20,000 values of 128 bytes: 2,555,904 point bytes kept per rejected batch, while ramBytesUsed grew by 185,624, 92,808 and 92,816 bytes over three rejected batches, each measured after one small successful document because the failed update does not refresh the counter).

• Who is exposed. Users of the experimental IndexWriter#addBatch (and updateDocuments(Term|Query, ColumnBatch), which share the code) with a DENSE LongColumn that indexes points (INT, FLOAT, LONG, DOUBLE) or a DENSE BinaryColumn with point dimensions, in 10.5.0, 10.5.1, 10.5.2, 10.6.0 (by reading) and main.
• Default or opt-in. The column API is opt-in; nothing else is: new IndexWriterConfig() with only the codec set, to the production default codec, and the default directory reproduce it, with assertions on and off.
• What it takes. More values than one chunk (1025 4-byte, 513 8-byte or 4096/width + 1 N-D values; ordinary batch sizes: the API author's motivating workload was batches of 1000), a failure at or after the first chunk boundary (a throwing cursor or a wrong-width value), and more points of the same field added to the same in-memory segment before it flushes.
• What breaks. Exact and range queries on the field, and any filter built on them, match the wrong documents. Their doc values keep the right values, so points and doc values disagree: a probe matched 5 later documents indexed with level = 5 with IntPoint.newRangeQuery("level", 0, 3) while their doc values said 5.
• Silent and lasting. No tragic exception, the writer stays open, CheckIndex is clean, and forceMerge(1) keeps the wrong values.
• Not affected. A failure inside the first chunk; documents added after a commit() that followed the failure (they go to a new segment); the sparse points path; the row API (addDocument) with the same bad value.
• How likely. Rare. Real callers usually build and validate point bytes before the call; the only downstream adopter found keeps this path behind an off-by-default flag and validates values first. With concurrent indexing threads, a commit() after the failure is not a full guard (another thread may add to the same segment first; not executed).

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: live docs matching p=7, p=1000 expected:<[1, 0]> but was:<[0, 1]>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:120)
       org.apache.lucene.index.TestRejectedDensePointsBatch.testRejectedBatchLeavesNoPointValues(TestRejectedDensePointsBatch.java:99)

• The rule is written down for the API's dense vectors writer. KnnFieldVectorsWriter#addDenseValues, merged in a9779ef3c193 (#16734): "The cursor may throw while it is being consumed, for example when a vector fails validation. In that case the documents of the whole batch are marked as deleted, but the writer must remain in a consistent state: every doc ID it has recorded must have its vector. ... record doc IDs and vectors only after fill has returned." (KnnFieldVectorsWriter.java:46-50). The flat vectors writer follows it (Lucene99FlatVectorsWriter.java:507-531), and testDenseVectorValidationFailureRecovers keeps the failed and the recovery batch in one segment "so flush checks that the vectors writer was left consistent" (TestColumnBatchIndexing.java:886-922). It is written for vectors; for points it is a strong analogy, not a documented contract. The dense numeric doc-values writers break it too (LFV-097).
• Non-aborting failures must leave consistent state. DocumentsWriter: non-aborting exceptions "can still partially update the index structures. These updates are consistent" and the document is marked deleted (DocumentsWriter.java:76-79); IndexWriter#addDocument: after an exception "the index will be consistent" (IndexWriter.java:1465); #16270 aligned updateBatch's exception handling with updateDocuments.
• Lucene raises the failure itself. The default fillPackedPoints "validates each length" and throws (BytesRefValuesCursor.java:67-80); the sparse path checks before writing (PointValuesWriter.java:78-86), and the row API rejects the same 3-byte value cleanly.
• Upstream tests inject throwing dense cursors. ThrowingDenseLongColumn (ColumnBatchTestUtil.java:642-701) and testLongValuesCursorThrowMidBatchRecovers (TestColumnBatchIndexing.java:740-792) assert recovery; they miss this because they use doc-values fields, 6-document batches and a commit() before the recovery documents.
• Sibling code keeps alignment. SortedDocValuesWriter.addDenseOrdinalValues commits only the processed values in a finally block (SortedDocValuesWriter.java:168-182).
• Buffer-size dependent. A bad last value in a 1024-value batch recovers; in a 1025-value batch it corrupts the next documents. Before #16227 the chunk was 1 KiB, and 129 long values sufficed.
• No document accepts it. No javadoc, CHANGES or MIGRATE entry, test or issue describes poisoned same-segment state after a rejected batch.

The strongest case for "not a bug" (the cross-model reviews, an independent reviewer from another model family, OpenAI GPT-5.6, voted "not real" on it): both triggers break documented cursor preconditions. The cursor "produces exactly size() values" (LongValuesCursor.java:22, BytesRefValuesCursor.java:22), BinaryColumn callers are "responsible for producing sort-encoded bytes of the correct total length" (BinaryColumn.java:28-29), addBatch is @lucene.experimental and, unlike addDocuments, does not point to addDocument's consistency note (IndexWriter.java:1528-1539 vs :1510-1511), and #16227 chose the 4 KiB staging for throughput.

Why it fails: Lucene checks the width itself and turns it into a non-aborting rejection, so it must leave the writer consistent; the vectors writer of the same API now documents that a cursor may throw and the writer must stay consistent; upstream's own tests inject throwing dense cursors; the damage lands on later, valid documents, not on the rejected batch; and the fix keeps the 4 KiB staging. The reviews agreed on the root cause and that the fix removes it, and the intended-lens review recommended that maintainers accept the fix; the independent reproducer, the devil's-advocate verifier and the adjudication rejected the argument. The rebuttal is not airtight: Lucene checking the width does not make a malformed value valid input, and the vectors rule is an analogy for points, not a documented points or addBatch contract. Verdict: not intended in the adjudication's and the verifiers' view; expect "hardening" as a possible label.

One fix was built and validated (option A); options B to D are alternatives that were not run.

In addDense1DIntValues, addDense1DLongValues and addDenseNDValues, count the values whose bytes were appended and commit that many doc IDs even when the cursor throws, as SortedDocValuesWriter.addDenseOrdinalValues does. The failed batch's documents are deleted anyway. The same change in all three methods, +39/-21 lines; applies with git apply on a9779ef3c193.

int written = 0;
try {
  while (written < size) {
    int chunk = Math.min(POINTS_BUFFER_INT_VALUES, size - written);
    cursor.fillIntPoints(buffer, 0, chunk);
    bytesOut.writeBytes(buffer, 0, chunk * Integer.BYTES);
    written += chunk;
  }
} finally {
  // keep docIDs aligned with the bytes already written, even if the cursor threw
  if (written > 0) {
    commitDenseRange(firstDocID, written, ramBefore);
  }
}

Trade-offs

• Keeps the 4 KiB staging and one writeBytes per chunk; also closes the RAM-accounting gap, because the written bytes are counted.
• The deleted documents of the failed batch keep up to written point values until a merge drops them (or until the flush drops the segment, if all its documents are deleted), like the points of any deleted document; that segment's point statistics (count, min/max) include them.
• No benchmark was run; the change adds one try/finally per call, not per chunk.

What the checks validated

• Gradle, scratch worktree of a9779ef3c193 (removed afterwards), 2026-10-27, seed DEADBEEF: the paste-ready test passes with assertions on and off (3 tests, 0 failures; stock: 2 failures).
• 11 closest suites (org.apache.lucene.document.column.*, TestColumnBatchIndexing, TestPointValues, TestPointQueries, TestIndexWriterExceptions, TestIndexWriterExceptions2): 296 tests, 0 failures, 5 skipped, assertions on and off (the same on stock, assertions on).
• :lucene:core:check -x test with the test file passes; all of :lucene:core:test: 749 classes, 8,892 tests, 0 failures, 0 errors, 322 skipped.
• Earlier, on the jar: the finder's repro, the independent reproducer's 5 tests, the intended-lens reviewer's 2 recovery-contract tests and 15 existing dense-points and recovery tests, and the security probe all pass with it; the same fix at the introducing commit 3d8956815579 passes.

Fill all values into a temporary buffer and append once, after the cursor has returned.

Trade-offs

Atomic, but needs size * width extra heap per call and undoes the 4 KiB staging of #16227. Not run.

Remember the buffer position before the loop and truncate to it in a catch.

Trade-offs

bytesOut is a PagedBytes.PagedBytesDataOutput, which can only append (writeByte, writeBytes) and report getPosition (PagedBytes.java:376-428); neither it nor PagedBytes can truncate or rewind the written bytes (only the read-side PagedBytesDataInput has setPosition, :321), so it needs a new method. Not run.

Abort the in-memory segment instead of rejecting only the batch.

Trade-offs

Discards every document buffered since the last flush, far more than the rejected batch. Not recommended; not run.

Method: an SMT (Z3) model of the dense column-pass writers, then failure injection on the jar (semi-formal: the hypothesis came from code reading while modelling).

• The hunt unit modelled the column-pass writers of addBatch (model/dense_commit.py). Obligation W2, "dense points failure-atomic", is VIOLATED for point widths 4, 8, 16 and 32 bytes; the smallest batch is one chunk plus one value (1025, 513, 257 and 129 values), leaving 1024, 512, 256 and 128 orphan values.
• A failure-injection sweep on the stock jar (harness/FailureInjectionSweep.java, 605 grid points per mode, assertions on and off) found violations in every dense points mode: dense binary 16-byte points with a throwing cursor 168 and with a wrong-length value 168, dense long INT points 18, dense long LONG points 78; the sparse long points control 0.
• The finder turned it into a JUnit on the stock jar; an independent reproducer, cross-model reviewers and a devil's-advocate verifier then wrote their own tests.