One binary doc-values update that matches many documents overflows an int-sized buffer at commit, and IndexWriter closes itself

IndexWriter.updateBinaryDocValue(term, field, value) buffers one term and one value (stored twice when it is the field's first update in the packet, on 7.7.0 and later). When the update is applied (at commit(), and by code reading also at a flush or NRT reopen that applies the packet), Lucene calls BinaryDocValuesFieldUpdates.add(doc, value) once for every document the term matches in a segment, and each call appends a full copy of the value to one int-sized byte[]. At 2^31 bytes the length wraps: ArrayIndexOutOfBoundsException (an AssertionError "likely integer overflow?" with assertions on). The apply runs inside an event that treats any Throwable as tragic, so IndexWriter closes itself and the update and every uncommitted document are lost; the last commit stays readable. 2,100 documents x 1 MiB fail, and so do 530,000 x 4 KiB; since 7.7.0 a lone update is applied twice (LFV-837), so 1,100 x 1 MiB fails too. With a one-method fix the same commit succeeds. Every tested release from 4.8.0 to 10.5.2 is affected, and so are main and, by reading, 10.6.0 (13 versions executed; the releases in between keep the same per-document append).

• Doc-values update: updateBinaryDocValue(term, field, value) (also updateDocValues(term, BinaryDocValuesField)) changes a binary doc-values field in place on every document that contains term. IndexWriter buffers the request and applies it later, at a commit, flush or NRT reopen, by looking up the term in each segment.
• Packet: the buffered updates that are applied together. Applying a packet builds one BinaryDocValuesFieldUpdates per field and segment, which records (doc, value) for every matched document before it is written out.
• Tragic event: an error after which IndexWriter closes itself and discards everything not committed, because its internal state may be inconsistent.

1. FrozenBufferedUpdates.applyDocValuesUpdates creates one BinaryDocValuesFieldUpdates per field and segment (FrozenBufferedUpdates.java:307-308) and, for each document the update's term matches, calls update.add(doc, binaryValue) with the same BytesRef (:319, loop :336-345). The numeric path keeps one value for all documents in this case (SingleValueNumericDocValuesFieldUpdates, :288-295); the binary path does not.
2. BinaryDocValuesFieldUpdates.add appends a full copy every time: offsets.set(index, values.length()); lengths.set(index, value.length); values.append(value); (BinaryDocValuesFieldUpdates.java:94-99), into values = new BytesRefBuilder() (:80), one byte[].
3. BytesRefBuilder.append computes the new length as ref.length + len, an int (BytesRefBuilder.java:77-80). With 2,047 copies of 1 MiB stored (2,146,435,072 bytes), copy 2,048 needs 2^31 bytes and the sum wraps to -2,147,483,648. ArrayUtil.grow asserts minSize >= 0 ("likely integer overflow?", ArrayUtil.java:446); without assertions it returns the array unchanged and System.arraycopy throws (BytesRefBuilder.java:79). (1 MiB and 4 KiB divide 2^31; for lengths where a multiple lands between ArrayUtil.MAX_ARRAY_LENGTH and Integer.MAX_VALUE, such as any length up to 16 bytes, ArrayUtil.oversize throws IllegalArgumentException instead, ArrayUtil.java:145-152, by code reading; the writer closes the same way.)
4. The apply runs as an event that catches any Throwable and calls onTragicEvent(t, "applyUpdatesPacket") (IndexWriter.java:2935-2943). commit() first flushes the buffered documents to a new segment (:3809, :3819; here doc late becomes segment _1, written but in no commit) and then applies the packet in processEvents(false) (:3821), as an executed infoStream probe shows. prepareCommitInternal then closes the writer through maybeCloseOnTragicEvent() -> rollbackInternal() (its finally at :3883 with assertions off; its catch (Error) at :3879-3881 with assertions on; :6098-6105), which drops segment _1 too.
5. Nothing bounds the expansion: the per-segment updates are built privately during the apply and enter IndexWriter's RAM accounting only when published (ReadersAndUpdates.java:153-161), and only the entry count has an explicit guard (DocValuesFieldUpdates.java:375-379).

By code reading the count that matters is the sum, over all binary updates of one field in one packet, of the documents each matches in one segment times its value length; only the one-update case was executed. Since 7.7.0 the first update of a field in a packet is applied twice (LFV-837), so a lone update fails at 2^30 bytes.

• Who is hit. Callers of updateBinaryDocValue, updateDocValues(term, BinaryDocValuesField) or softUpdateDocument(s) with a binary doc-values field (the last two by code reading), when the term matches many documents of one segment.
• Default vs opt-in. Default IndexWriterConfig and codec (executed). The tests use ByteBuffersDirectory; an FSDirectory variant fails the same way (executed), since the overflow happens in a heap buffer, before the update is written. Binary doc-values updates are an optional but mainstream public API; no RAM-buffer or heap setting bounds the expansion.
• Scale. 2,100 x 1 MiB; 1,100 x 1 MiB when the update is its field's first in the packet (any lone update, 7.7.0 and later); 530,000 x 4 KiB. Controls with 100 or 1,000 x 1 MiB and 200,000 x 4 KiB succeed. The failing apply needs about 4 GB of heap; with a 3 GB heap it ends in OutOfMemoryError instead, with the same close. The 530,000-document test forces one segment with forceMerge(1); in practice the trigger needs large segments and a term that many of their documents share.
• Effect. Loud: commit() throws and the writer is closed. The update and every acknowledged uncommitted document are lost; the last commit stays readable and a new writer opens on it (executed). Before 7.0.0 the writer stays open but stuck: a second commit() and close() throw the same exception and late is missing after reopening (executed on 4.8.0, 4.10.4, 5.5.5, 6.6.6); by code reading every later commit fails too and close() rolls back.
• No way to apply it. A bigger heap does not help, since the limit is the int length; only keeping documents matched per segment times value length, summed over the field's binary updates in one packet, under 2^31 bytes avoids it: fewer matched documents, a smaller value or fewer updates per packet (by code reading).
• Likelihood. Rare: binary updates by a widely shared term are uncommon (most in-place updates are numeric or by primary key), and nobody has reported it since 4.8.0 (2014).

The test uses ByteBuffersDirectory, new IndexWriterConfig(null) and NoMergePolicy so that the 2,100 documents stay in one segment; the independent reproducer's test (below) shows the same with a fully default new IndexWriterConfig(). Set -Dh321.numDocs=N (as -Ptests.jvmargs) to change the number of documents. The failing run allocates about 4 GB; with a 3 GB heap the same update ends in OutOfMemoryError, with the same close.

The other files: the independent reproducer's test (default config, a 100-document control, checks that a new writer opens), the devil's-advocate checker's 530,000 x 4 KiB test, and a small-heap unit test, which checks BinaryDocValuesFieldUpdates directly (it fails on stock main and passes with the fix). The verifier tests are not yet formatted with google-java-format.

On stock main: the 2,100-document test fails, the 100-document control passes; a new writer opens after the close.

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.lucene.index;

import java.io.PrintWriter;
import java.io.StringWriter;
import java.util.Arrays;
import org.apache.lucene.document.BinaryDocValuesField;
import org.apache.lucene.document.Document;
import org.apache.lucene.document.Field;
import org.apache.lucene.document.StringField;
import org.apache.lucene.search.IndexSearcher;
import org.apache.lucene.search.TermQuery;
import org.apache.lucene.store.ByteBuffersDirectory;
import org.apache.lucene.store.Directory;
import org.apache.lucene.tests.util.LuceneTestCase;
import org.apache.lucene.util.BytesRef;

/**
 * One call to {@link IndexWriter#updateBinaryDocValue(Term, String, BytesRef)} whose term matches
 * many documents of one segment. The javadoc documents no size limit and says the value replaces
 * the value of all affected documents. Expected: the commit succeeds, the writer stays open, the
 * acknowledged document added before the update is committed and every matched document reads
 * back the new value.
 *
 * <p>Heap: the failing run needs about 4 GB (the per-document copies of the value); run with
 * -Xmx8g. The control method needs far less.
 */
public class TestBinaryDvUpdateManyDocs extends LuceneTestCase {

  private static final int VALUE_LEN = 1 << 20; // 1 MiB

  /** 2,100 documents x 1 MiB = 2,100 MiB of updated values in one segment (> 2^31 bytes). */
  public void testUpdateMatchingManyDocs() throws Exception {
    runScenario(Integer.getInteger("v1.numDocs", 2100));
  }

  /** Control: the same scenario with 100 documents (100 MiB) must work on every version. */
  public void testControlFewDocs() throws Exception {
    runScenario(100);
  }

  private static void runScenario(int numDocs) throws Exception {
    byte[] big = new byte[VALUE_LEN];
    for (int i = 0; i < big.length; i++) {
      big[i] = (byte) (i * 31 + 7);
    }
    try (Directory dir = new ByteBuffersDirectory()) {
      IndexWriter w = new IndexWriter(dir, new IndexWriterConfig());
      for (int i = 0; i < numDocs; i++) {
        Document d = new Document();
        d.add(new StringField("id", "d" + i, Field.Store.NO));
        d.add(new StringField("group", "g", Field.Store.NO));
        d.add(new BinaryDocValuesField("bdv", new BytesRef(new byte[] {1})));
        w.addDocument(d);
      }
      w.commit();
      try (DirectoryReader r = DirectoryReader.open(dir)) {
        assertEquals("setup: one segment", 1, r.leaves().size());
        assertEquals(numDocs, r.numDocs());
      }

      // An unrelated, acknowledged but not yet committed document.
      Document late = new Document();
      late.add(new StringField("id", "late", Field.Store.NO));
      late.add(new BinaryDocValuesField("bdv", new BytesRef(new byte[] {2})));
      w.addDocument(late);

      // One update whose term matches all numDocs documents of the committed segment.
      w.updateBinaryDocValue(new Term("group", "g"), "bdv", new BytesRef(big));

      Throwable failure = null;
      try {
        w.commit();
      } catch (Throwable t) {
        failure = t;
      }
      boolean open = w.isOpen();
      Throwable tragic = w.getTragicException();
      if (open) {
        w.close();
      }

      int committedDocs;
      int lateHits;
      try (DirectoryReader r = DirectoryReader.open(dir)) {
        committedDocs = r.numDocs();
        lateHits = new IndexSearcher(r).count(new TermQuery(new Term("id", "late")));
        if (failure == null) {
          // spot-check updated values on a few matched documents
          for (LeafReaderContext ctx : r.leaves()) {
            BinaryDocValues bdv = ctx.reader().getBinaryDocValues("bdv");
            assertNotNull(bdv);
            int checked = 0;
            for (int doc = 0; doc < ctx.reader().maxDoc() && checked < 3; doc += 997) {
              assertTrue(bdv.advanceExact(doc));
              BytesRef v = bdv.binaryValue();
              if (v.length == VALUE_LEN) {
                assertTrue(
                    "value mismatch at doc " + doc,
                    Arrays.equals(big, 0, VALUE_LEN, v.bytes, v.offset, v.offset + v.length));
                checked++;
              }
            }
          }
        }
      }
      // A new writer on the same directory opens fine (the failure does not persist).
      boolean reopenedWriterOk;
      try (IndexWriter w2 = new IndexWriter(dir, new IndexWriterConfig())) {
        reopenedWriterOk = w2.isOpen();
      }

      String report =
          "numDocs="
              + numDocs
              + " valueLen="
              + VALUE_LEN
              + " product="
              + ((long) numDocs * VALUE_LEN)
              + " (2^31="
              + (1L << 31)
              + ")\n  commit failure: "
              + describe(failure)
              + "\n  writer open after commit: "
              + open
              + "\n  tragic exception: "
              + (tragic == null ? "null" : tragic.getClass().getName() + ": " + tragic.getMessage())
              + "\n  after reopen: committed docs="
              + committedDocs
              + ", late doc present="
              + (lateHits == 1)
              + ", new writer opens="
              + reopenedWriterOk;
      System.out.println("V1-REPORT " + report);

      assertNull("commit must not fail\n" + report, failure);
      assertTrue("writer must stay open\n" + report, open);
      assertNull("no tragic exception\n" + report, tragic);
      assertEquals("all docs incl. the late one committed\n" + report, numDocs + 1, committedDocs);
      assertEquals("late doc committed\n" + report, 1, lateHits);
    }
  }

  private static String describe(Throwable t) {
    if (t == null) {
      return "none";
    }
    StringWriter sw = new StringWriter();
    t.printStackTrace(new PrintWriter(sw));
    String[] lines = sw.toString().split("\n");
    StringBuilder sb = new StringBuilder();
    for (int i = 0; i < Math.min(14, lines.length); i++) {
      sb.append("\n      ").append(lines[i].trim());
    }
    return sb.toString();
  }
}

On stock main and 10.5.2: fails the same way; 200,000 documents pass.

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.lucene.index;

import org.apache.lucene.document.BinaryDocValuesField;
import org.apache.lucene.document.Document;
import org.apache.lucene.document.Field;
import org.apache.lucene.document.StringField;
import org.apache.lucene.store.ByteBuffersDirectory;
import org.apache.lucene.store.Directory;
import org.apache.lucene.tests.util.LuceneTestCase;
import org.apache.lucene.util.BytesRef;

/**
 * Reachability check with a moderate value size: one updateBinaryDocValue call with a 4 KiB value
 * whose term matches 530,000 documents of one segment (530,000 x 4,096 bytes > 2^31 - 1). Default
 * IndexWriterConfig (default merge policy, default RAM buffer). Expected per the javadoc: the update
 * is applied and the writer stays open.
 */
public class TestModerateValueBinaryUpdate extends LuceneTestCase {

  public void testModerateValueManyDocs() throws Exception {
    final int numDocs = Integer.getInteger("v3.numDocs", 530_000);
    final int valueLength = Integer.getInteger("v3.valueLength", 4096);
    try (Directory dir = new ByteBuffersDirectory()) {
      IndexWriter w = new IndexWriter(dir, new IndexWriterConfig(null));
      for (int i = 0; i < numDocs; i++) {
        Document doc = new Document();
        doc.add(new StringField("tenant", "t1", Field.Store.NO));
        doc.add(new BinaryDocValuesField("blob", new BytesRef(new byte[] {(byte) i})));
        w.addDocument(doc);
      }
      w.forceMerge(1);
      w.commit();
      int segs;
      try (DirectoryReader r = DirectoryReader.open(w)) {
        segs = r.leaves().size();
      }
      byte[] v = new byte[valueLength];
      for (int i = 0; i < v.length; i++) {
        v[i] = (byte) (i * 13 + 1);
      }
      w.updateBinaryDocValue(new Term("tenant", "t1"), "blob", new BytesRef(v));
      Throwable failure = null;
      try {
        w.commit();
      } catch (Throwable t) {
        failure = t;
      }
      System.out.println(
          "segments="
              + segs
              + " numDocs="
              + numDocs
              + " valueLength="
              + valueLength
              + " product="
              + ((long) numDocs * valueLength)
              + " failure="
              + failure
              + " writerOpen="
              + w.isOpen()
              + " tragic="
              + w.getTragicException());
      assertNull("commit after an accepted binary doc-values update threw: " + failure, failure);
      assertTrue("IndexWriter closed itself", w.isOpen());
      w.close();
    }
  }
}

10,000 documents get the same 1 KiB value; ramBytesUsed() must stay under a tenth of the 10,240,000 bytes of copies. Stock: fails (ramBytesUsed=11320434); with the fix: passes. A second, randomized test (runs of values, resets, a reused BytesRef) passes on both.

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.lucene.index;

import org.apache.lucene.search.DocIdSetIterator;
import org.apache.lucene.tests.util.LuceneTestCase;
import org.apache.lucene.util.BytesRef;
import org.apache.lucene.util.BytesRefBuilder;

/**
 * Small-heap unit tests for BinaryDocValuesFieldUpdates: applying one buffered binary update adds
 * the same value for every document its term matches, so the value bytes kept must not grow with
 * the number of matched documents.
 */
public class TestBinaryDocValuesFieldUpdatesSharedValue extends LuceneTestCase {

  /** 10,000 documents get the same 1 KiB value: keeping 10,000 copies costs 10,240,000 bytes. */
  public void testSameValueOnManyDocsIsStoredOnce() {
    final int numDocs = 10_000;
    final byte[] bytes = new byte[1024];
    random().nextBytes(bytes);
    final BytesRef value = new BytesRef(bytes);
    BinaryDocValuesFieldUpdates updates = new BinaryDocValuesFieldUpdates(0, "f", numDocs);
    for (int doc = 0; doc < numDocs; doc++) {
      updates.add(doc, value);
    }
    updates.finish();
    long copies = (long) numDocs * bytes.length;
    assertTrue(
        "ramBytesUsed=" + updates.ramBytesUsed() + " for " + copies + " bytes of copies",
        updates.ramBytesUsed() < copies / 10);
    DocValuesFieldUpdates.Iterator it = updates.iterator();
    for (int doc = 0; doc < numDocs; doc++) {
      assertEquals(doc, it.nextDoc());
      assertTrue(it.hasValue());
      assertEquals(value, it.binaryValue());
    }
    assertEquals(DocIdSetIterator.NO_MORE_DOCS, it.nextDoc());
  }

  /**
   * Runs of different values (including empty ones), documents in random order and updated more
   * than once, resets, and a caller that reuses one BytesRef and overwrites its bytes between runs:
   * every document must read back its last value.
   */
  public void testRunsOfValuesReadBackLastValue() {
    final int maxDoc = 200;
    final byte[][] pool = new byte[5][];
    for (int i = 0; i < pool.length; i++) {
      pool[i] = new byte[i == 0 ? 0 : 1 + random().nextInt(40)];
      random().nextBytes(pool[i]);
    }
    for (int iter = 0; iter < 50; iter++) {
      BinaryDocValuesFieldUpdates updates = new BinaryDocValuesFieldUpdates(0, "f", maxDoc);
      byte[][] expected = new byte[maxDoc][]; // null: no entry
      boolean[] reset = new boolean[maxDoc];
      BytesRefBuilder reused = new BytesRefBuilder();
      int runs = 1 + random().nextInt(20);
      for (int run = 0; run < runs; run++) {
        if (random().nextInt(10) == 0) {
          int doc = random().nextInt(maxDoc);
          updates.reset(doc);
          expected[doc] = null;
          reset[doc] = true;
          continue;
        }
        byte[] v = pool[random().nextInt(pool.length)];
        BytesRef ref;
        if (random().nextBoolean()) {
          reused.copyBytes(v, 0, v.length); // same object, new bytes
          ref = reused.get();
        } else {
          byte[] padded = new byte[v.length + 3];
          System.arraycopy(v, 0, padded, 1, v.length);
          ref = new BytesRef(padded, 1, v.length);
        }
        int matches = 1 + random().nextInt(30);
        for (int m = 0; m < matches; m++) {
          int doc = random().nextInt(maxDoc);
          updates.add(doc, ref);
          expected[doc] = v;
          reset[doc] = false;
        }
      }
      updates.finish();
      DocValuesFieldUpdates.Iterator it = updates.iterator();
      for (int doc = 0; doc < maxDoc; doc++) {
        if (expected[doc] == null && reset[doc] == false) {
          continue;
        }
        assertEquals(doc, it.nextDoc());
        if (reset[doc]) {
          assertFalse("doc " + doc, it.hasValue());
        } else {
          assertTrue("doc " + doc, it.hasValue());
          assertEquals("doc " + doc, new BytesRef(expected[doc]), it.binaryValue());
        }
      }
      assertEquals(DocIdSetIterator.NO_MORE_DOCS, it.nextDoc());
    }
  }
}

cp $REPRO/org/apache/lucene/index/TestBinaryDocValuesUpdateBufferOverflow.java \
   $LUCENE/lucene/core/src/test/org/apache/lucene/index/
cd $LUCENE && ./gradlew :lucene:core:test --tests TestBinaryDocValuesUpdateBufferOverflow \
   -Ptests.heapsize=8g -Ptests.seed=DEADBEEF
# add -Ptests.asserts=false for the ArrayIndexOutOfBoundsException
# with a fix: -Ptests.heapsize=12g (the committed 2.2 GB live in the heap directory)

# stock main a9779ef3c193, gradle, assertions on
TestBinaryDocValuesUpdateBufferOverflow > testBinaryUpdateMatchingManyDocsKeepsWriterOpen FAILED
    java.lang.AssertionError: commit of an accepted binary doc-values update threw: java.lang.AssertionError:
        size must be positive (got -2147483648): likely integer overflow? expected null, but was:<...>
  1> numDocs=2100 commit failure: java.lang.AssertionError: size must be positive (got -2147483648): likely integer overflow?;
     writer open: false; tragic exception: java.lang.AssertionError: size must be positive (got -2147483648): likely integer overflow?
  1> after the close: committed docs=2100, acknowledged late doc present=false

# the same with -Ptests.asserts=false
  1> numDocs=2100 commit failure: java.lang.ArrayIndexOutOfBoundsException: arraycopy: last destination index 2147483648
     out of bounds for byte[2147483631]; writer open: false; tragic exception: java.lang.ArrayIndexOutOfBoundsException: ...
  1> after the close: committed docs=2100, acknowledged late doc present=false

# the failed commit's stack (independent reproducer's test, same build, assertions on)
java.lang.AssertionError: size must be positive (got -2147483648): likely integer overflow?
    at org.apache.lucene.util.ArrayUtil.grow(ArrayUtil.java:446)
    at org.apache.lucene.util.BytesRefBuilder.grow(BytesRefBuilder.java:60)
    at org.apache.lucene.util.BytesRefBuilder.append(BytesRefBuilder.java:78)
    at org.apache.lucene.util.BytesRefBuilder.append(BytesRefBuilder.java:85)
    at org.apache.lucene.index.BinaryDocValuesFieldUpdates.add(BinaryDocValuesFieldUpdates.java:98)
    at org.apache.lucene.index.FrozenBufferedUpdates.lambda$applyDocValuesUpdates$2(FrozenBufferedUpdates.java:319)
    at org.apache.lucene.index.FrozenBufferedUpdates.applyDocValuesUpdates(FrozenBufferedUpdates.java:342)
    at org.apache.lucene.index.FrozenBufferedUpdates.applyDocValuesUpdates(FrozenBufferedUpdates.java:205)
    at org.apache.lucene.index.FrozenBufferedUpdates.apply(FrozenBufferedUpdates.java:173)
    at org.apache.lucene.index.IndexWriter.forceApply(IndexWriter.java:6592)
    at org.apache.lucene.index.IndexWriter.tryApply(IndexWriter.java:6494)
    at org.apache.lucene.index.IndexWriter.lambda$publishFrozenUpdates$0(IndexWriter.java:2939)
  writer open after commit: false
  after reopen: committed docs=2100, late doc present=false, new writer opens=true

# with the fix (same worktree): the test passes with assertions on and off (3.2 s, 12 GB test heap)

• Contract. updateBinaryDocValue (IndexWriter.java:1981-1995): "NOTE: this method currently replaces the existing value of all affected documents with the new value", with @param term the term to identify the document(s) to be updated; no size limit. updateDocValues (:2059-2063): "Each field update is applied to the set of documents that are associated with the Term to the same value."
• A legal result. The indexing-time BinaryDocValuesWriter stores values in PagedBytes and allows each value up to ArrayUtil.MAX_ARRAY_LENGTH (BinaryDocValuesWriter.java:40-45, 61, 81-83); with the fix the same 2.2 GB update commits in one segment and all values read back (executed).
• Lucene's own check flags it. ArrayUtil.grow: "size must be positive (got -2147483648): likely integer overflow?" (ArrayUtil.java:446). The entry count has an explicit guard, "cannot support more than Integer.MAX_VALUE doc/value entries" (DocValuesFieldUpdates.java:375-379); the byte length has none.
• History. The per-document append came with the feature (LUCENE-5513, #6576, 2014); in that issue @shaie, who implemented it, notes that the update "makes all affected documents identical", and no comment discusses the size of the in-heap buffer the apply builds. LUCENE-8593 (b4e1fe4393b, 2018) gave the numeric path a single-value specialisation; the binary path never got one.
• Tests and precedent. No test, javadoc, CHANGES or MIGRATE entry accepts the failure. #8589 (LUCENE-7538), an 800 MB stored field whose int overflow closed the writer, was fixed by rejecting the input with a clear error.

The strongest intended-behaviour case, built by a dedicated checker: "the limits on IndexWriter are 2GB" (a maintainer on #15330), and IndexWriterConfig documents another sub-2 GB limit, the per-thread RAM hard limit (IndexWriterConfig.java:373-385); BinaryDocValuesField says values "are stored directly with no sharing" (BinaryDocValuesField.java:26-28); the class is @lucene.experimental; the writer closing after a failed apply is an intended fail-safe since LUCENE-7868; and the IndexWriter class NOTE ("if you hit an Error ... IndexWriter will close itself", IndexWriter.java:162-165) covers the AssertionError of an -ea run and the OutOfMemoryError of a small heap.

Why it fails: the #15330 remark is about an indexing buffer that the RAM settings bound, and the per-thread limit is a setting checked with a clear error, while here one 1 MiB value is buffered and the 2 GiB appear at apply time with no check; "no sharing" is storage advice, and only NUMERIC, SORTED_NUMERIC and BINARY fields can be updated (IndexWriter.java:2106-2124), so BINARY is the only updatable byte type; the experimental tag is on the internal class, not on updateBinaryDocValue; the close is intended, which is why the overflow, not the close, is the defect; the class NOTE explains the close for Errors but sets no limit on the update, and with assertions off (the production default) and an 8 GB heap the failure is an ArrayIndexOutOfBoundsException, which no document covers. Verdict: not intended.

One fix was built and validated in a clean scratch worktree at a9779ef3c193 (removed afterwards); it is the finder's sketch with java.util.Arrays imported. Fixing the separate bug LFV-837 alone only restores the 2 GiB threshold. Workaround today (by code reading, not executed): keep each packet under the limit, for example by splitting the term into parts and committing after each part, or keep the shared value in a separate document. Both have limits: splitting needs an indexed term the application can partition, and a separate document changes the application's data model.

In BinaryDocValuesFieldUpdates.add (:94-99), remember the offset and length of the last appended value; when the new value has the same bytes, point the document's offset at that copy instead of appending again. One update's documents arrive consecutively with the same value (FrozenBufferedUpdates.java:336-345), including the duplicate pass of LFV-837, so each update is stored once.

  // plus: import java.util.Arrays;
  private int lastOffset = -1;
  private int lastLength = -1;

  @Override
  public synchronized void add(int doc, BytesRef value) {
    int index = add(doc);
    if (value.length != lastLength
        || Arrays.equals(values.bytes(), lastOffset, lastOffset + lastLength,
                value.bytes, value.offset, value.offset + value.length) == false) {
      lastOffset = values.length();
      lastLength = value.length;
      values.append(value);
    }
    offsets.set(index, lastOffset);
    lengths.set(index, value.length);
  }

Trade-offs

• Also removes the heap blow-up: one 1 MiB copy instead of 2.2 GB while applying, and the published update's ramBytesUsed() (:135-143) no longer counts N copies.
• Compares with the stored copy, not the caller's BytesRef, so a reused or re-filled BytesRef is safe; swap() moves offsets and lengths together (:101-112), so shared offsets survive the sort in finish().
• Distinct values (by code reading): with the fix one apply buffer holds at most one copy per buffered update of the field, so no more value bytes than the packet buffered for that field, and those already sit in an int-addressed structure (FieldUpdatesBuffer.byteValues, a BytesRefArray with int offsets over a ByteBlockPool that advances with Math.addExact; FieldUpdatesBuffer.java:87, 111, 207-210, BytesRefArray.java:34-36, 64-72, ByteBlockPool.java:187-199). So about 2 GiB of distinct values for one field in one packet reaches that buffering limit at the same scale, before any apply; buffering that much takes a RAM buffer above 2 GB or flushing by document count only (FlushByRamOrCountsPolicy.java:34-52). The merge carry-over path (IndexWriter.java:4640-4687) also fills the buffer document by document, where the fix only shares a copy between consecutive equal values; not analysed further.
• Cost: one byte comparison per matched document, the size of the copy it replaces, inside the synchronized add(), so it lengthens the locked section; no performance or concurrency benchmark was run. A cheaper first check (same array, offset and length as the last call) is possible but untested.
• The end-to-end test needs 8-12 GB of heap (at most a @Monster test, like Test2BBinaryDocValues); the small-heap unit test TestBinaryDocValuesFieldUpdatesSharedValue suits CI.

What the checks validated

• Stock, gradle, seed DEADBEEF: the finder's test fails with assertions on and off; the new unit test fails (ramBytesUsed=11320434 for 10240000 bytes of copies); the verifiers' 2,100-document and 530,000 x 4 KiB tests fail, the 100-document control passes.
• With the fix: the finder's test passes with assertions on and off (12 GB test heap); the verifiers' tests and both new unit tests pass.
• With the fix: 16 classes, 221 tests, 5 skipped, 0 failures: TestBinaryDocValuesUpdates, TestNumericDocValuesUpdates, TestMixedDocValuesUpdates, TestSortedNumericDocValuesUpdates, TestDocValuesFieldUpdates, TestFieldUpdatesBuffer, TestBufferedUpdates, TestFrozenBufferedUpdates, TestIncrementalDocValuesUpdates, TestSoftDeletesRetentionMergePolicy, TestSoftDeletesDirectoryReaderWrapper, TestIndexWriterExceptions, TestDocValuesIndexing, TestAtomicUpdate, TestRollingUpdates and the new unit test.
• checkGoogleJavaFormat, ecjLintMain, ecjLintTest, forbiddenApisMain, forbiddenApisTest on lucene/core: clean for the changed file, the finder's test and the new unit test (only the verifier tests need reformatting).
• Earlier, the finder shadowed the same change onto the stock jars: the repro passes and 136 tests in 10 doc-values-update classes pass.

Store the values as BinaryDocValuesWriter does, in PagedBytes with long offsets.

Trade-offs

Still holds one copy per document (2.2 GB for the repro) while applying, and the iterator (:35-71, one BytesRef and int offsets) has to change. On its own it moves the limit to the heap; for many distinct values it would only matter if the buffering structure were made long-addressed too (by code reading). The first option alone fixes the executed failure.

Check the byte length in add and throw a descriptive exception, like the entry-count guard (DocValuesFieldUpdates.java:375-379).

Trade-offs

A guard inside add() still throws inside the apply event, so the writer still closes and the data is still lost; only the message improves. Rejecting the update cleanly would need a check outside the tragic event path, which is hard because the number of matched documents is known only during the apply, not when the update is buffered.

Method: semi-formal. In a hunt unit on packed, mutable and paged structures, the finder wrote a grid-based translation-validation harness (randomized operations and values) for the doc-values update buffers on the real jar: BinaryDocValuesFieldUpdates offsets, lengths and values checked against a TreeMap model, up to 4,097 updates per buffer and values up to 306 bytes, 2,393,731 checks, 0 mismatches.

• While modelling it, the finder noted that the value buffer is one BytesRefBuilder with an int length, a bound no small-scale check can reach, and that applying one update calls add once per matched document with the same value.
• The hypothesis was witnessed with a public-API JUnit on the stock main jar (2,100 documents x 1 MiB), then on 10.5.2, 9.12.3, 8.11.4, 8.0.0 and 7.6.0. No model checker or prover found the overflow itself; the model only pointed at the unchecked bound.