IndexWriter.tryUpdateDocValue never checks the RAM buffer, so pending updates grow the heap until the next refresh

IndexWriter.tryUpdateDocValue (Expert) updates a doc value of a document found through an NRT reader. Each successful call builds a new per-field update object and adds it straight to the segment's pending updates in the writer's reader pool. The writer's rule for those pending updates, "If the reader pool is > 50% of our IW buffer, then write the updates", runs only after a packet of buffered deletes or updates has been applied, which the try path never creates. So nothing ever compares the try-updates with the RAM buffer: they stay on the heap, about 334 bytes per numeric field update and about 530 per binary one (8-byte values), until an NRT refresh, flush(), commit, a merge of the segment or an unrelated term-based update writes them. With a 1 MB buffer, 10,000 calls on one document leave 3,340,000 bytes pending; with the default 16 MB buffer and a reader that is never refreshed, the heap grows linearly to OutOfMemoryError. IndexWriter.ramBytesUsed() does not count this memory. The same updates through updateNumericDocValue(Term, ...) stay bounded. Every release since the method arrived in 7.4.0 is affected; calling the existing rule after a successful try-update fixes it.

• Reader pool / pending updates: the writer keeps one ReadersAndUpdates per segment. Resolved doc-values updates wait there as DocValuesFieldUpdates objects, one list per field, until they are written as a new doc-values generation of the segment. ReadersAndUpdates.addDVUpdate documents the plan: "We buffer these in RAM and write to disk when too much RAM is used or when a merge needs to kick off, or a commit/refresh" (ReadersAndUpdates.java:148-151).
• The rule: IndexWriter.writeSomeDocValuesUpdates sums the reader pool and, "If the reader pool is > 50% of our IW buffer", writes the largest segments' pending updates (IndexWriter.java:807-884, test at :816; skipped when RAM flushing is disabled, :812). Its only call site runs after a frozen packet is applied: "Since we just resolved some more deletes/updates, now is a good time to write them" (:6599-6600).

1. public synchronized long tryUpdateDocValue(IndexReader readerIn, int docID, Field... fields) (IndexWriter.java:1721) builds the updates (:1724) and calls tryModifyDocument (:1725, defined at :1791-1829), which finds the segment's ReadersAndUpdates and runs the closure.
2. The closure takes a fresh generation (:1729), creates a new NumericDocValuesFieldUpdates or BinaryDocValuesFieldUpdates per field (:1740, :1743), adds the one document, then updates.finish(); rld.addDVUpdate(updates); (:1773-1776) and changed() (:1782). Nothing runs after it.
3. addDVUpdate appends the object (ReadersAndUpdates.java:163) and adds its size to the segment's counter (:161). It compares nothing.
4. A try-update creates no packet, so it never reaches the rule. Pending try-updates are written only by an NRT refresh, flush(), commit, a merge of the segment, or the packet apply of an unrelated term-based delete or update. An automatic RAM-triggered segment flush from adding documents, with no buffered term-based deletes or updates, does not write them (a flush that also publishes such a packet runs the rule through that packet's apply).
5. IndexWriter.ramBytesUsed() returns docWriter.ramBytesUsed() only (IndexWriter.java:795-799), so it reports 0 for all of this memory. It leaves out the reader pool on every path, so this is context, not a second bug.

Binary try-updates cost about 530 bytes per call with 8-byte values (522 with 2-byte values). Releases 7.4.0 to 8.11.4 account 302 bytes per numeric call (3,020,000 for the repro), an accounting difference only.

• Who is hit. Applications that call tryUpdateDocValue on a numeric, binary or soft-deletes field many times between NRT refreshes, flush() or commit, with no term-based delete or update in between: for example one try soft-delete or un-delete per document over a large segment (the javadoc names un-deleting a soft-deleted document as a use), or a stream of per-document counter updates while refresh is paused. Inside Lucene only two tests call it; a code search found no call in Elasticsearch, OpenSearch or Solr (2026-11-02).
• Default vs opt-in. The API is Expert and opt-in; everything else is the default IndexWriterConfig (16 MB buffer). The bug needs RAM-based flushing, which is the default: with RAM flushing disabled (DISABLE_AUTO_FLUSH, flushing by document count instead) the rule skips its check (IndexWriter.java:812), so no path has it and the try path no longer differs.
• Scale. Growth is per call, not per document. Between 562,500 and 750,000 numeric calls fill a 256 MB heap when the reader is never refreshed. One long bulk pass over a single reader, the natural way to resolve the doc ids, is enough.
• What bounds it. Any NRT refresh, flush(), commit, a merge of the segment, or an unrelated term-based delete or update. NRT applications that refresh every few seconds will rarely notice.
• What does not happen. No wrong search results, no index damage, no data loss. With assertions enabled each call also gets slower (an assertion scans the growing list); that is test-only and not part of the claim.

The smallest input: one segment with one document, and a loop of updates to that document. The oracle is the pooled segment's own byte counter (ReadersAndUpdates.ramBytesUsed), the value the writer's rule sums; it is a measured quantity read through internal API (an internal oracle), not a Java assert, and with assertions off the test fails identically. The test must sit in org.apache.lucene.index because IndexWriter.getPooledInstance and the counter are package-private, as in TestReaderPool. The assertion allows the whole 1 MB buffer, twice the rule's threshold, so it is lenient. The public symptom, OutOfMemoryError, needs about 600,000 calls per 256 MB of heap and is not part of the repro. The same test is the regression test. The test uses no random values, and every seed tried gives the same result: DEADBEEF, 5EED1234 and 1075FC01 give 3,340,000 bytes, and so does an earlier variant (it differs only in newDirectory(), a per-call return-value check and a longer message) under three more seeds and in 20 iterations.

# gradle, stock e1faeba08bde, seed DEADBEEF, assertions on (assertions off prints the same)
TestTryUpdateDocValueRamBuffer > testTryUpdateDocValueRespectsRamBuffer FAILED
    java.lang.AssertionError: pending doc-values updates use 3340000 bytes
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:34D5FB49BB02DD94]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.assertTrue(Assert.java:42)
        at org.apache.lucene.index.TestTryUpdateDocValueRamBuffer.testTryUpdateDocValueRespectsRamBuffer(TestTryUpdateDocValueRamBuffer.java:42)

# with fix A or fix B: the test passes, assertions on and off

# supplementary heap probe (not the repro): 16 MB buffer, reader never refreshed, -Xmx256m, heap after GC
mode=try    after 187500 calls: heap=73MiB | after 375000: 138MiB | after 562500: 202MiB | then java.lang.OutOfMemoryError: Java heap space
mode=update after 187500 calls: heap=13MiB | ... | after 1500000: 23MiB | all 1500000 calls accepted

• Contract and design statements. ReadersAndUpdates.addDVUpdate: "Adds a new resolved (meaning it maps docIDs to new values) doc values packet. We buffer these in RAM and write to disk when too much RAM is used or when a merge needs to kick off, or a commit/refresh." (ReadersAndUpdates.java:148-151). writeSomeDocValuesUpdates: "If the reader pool is > 50% of our IW buffer, then write the updates" (IndexWriter.java:811). setRAMBufferSizeMB: "Determines the amount of RAM that may be used for buffering added documents and deletions before they are flushed to the Directory." (LiveIndexWriterConfig.java:158-159). The IndexWriter class javadoc: "These changes are buffered in memory and periodically flushed to the Directory" (IndexWriter.java:123-124). The tryUpdateDocValue javadoc (:1707-1720) says nothing about memory and does not ask callers to refresh for it.
• The sibling paths are bounded. Term-based updates are held first by the buffered-updates RAM trigger and, once a packet apply resolves them into the pool, by the rule: 200,000 term updates with a 1 MB buffer leave 371,596 bytes in the pool, below half the buffer. tryDeleteDocument creates no doc-values updates; it writes into a fixed-size live-docs bitset. A merge also adds resolved updates to the merged segment (IndexWriter.java:4526-4542), but only the ones that resolved on its source segments while it ran, remapped once per merge, so it adds no growth of its own. Upstream TestNumericDocValuesUpdates.testUpdatesAreFlushed sets a tiny RAM buffer and asserts that getFlushDeletesCount() goes up after each term-based update; it does not look at the reader pool or the 50% rule. No upstream test covers memory on the try path or relies on the unbounded behaviour.
• History: no record of a decision to exempt this path. LUCENE-7868 (58105a203a1, 2017-06-21, 7.0.0) added the rule. LUCENE-8297 (b0b32931b28, 2018-05-05, 7.4.0) added tryUpdateDocValue on tryModifyDocument, shared with tryDeleteDocument, and added no check; #9344 never mentions RAM.
• Precedent. LUCENE-5248 (#6312, 2013, fixed in 4.6) fixed the same symptom on the then term-based path, where resolved updates would "just keep accumulating there, until RAM is exhausted".

The strongest case for "works as designed" (built by the devil's-advocate verifier; the cross-model reviews and the adjudication rated it moderate): the RAM buffer names only "added documents and deletions", "is just an indicator when to flush" (LiveIndexWriterConfig.java:166-172) and may release only part of the buffer, depending on the FlushPolicy (:179-181); ReadersAndUpdates is package-private, so its javadoc states design intent, not a public contract; the API is Expert and tied to an NRT reader the caller is expected to refresh, and the same javadoc already tells delete-by-Query users to "compensate by either calling commit() or refresh() periodically yourself" (:174-177).

Why it fails: the "indicator" and FlushPolicy caveats allow overshoot from flushes that run while other threads keep adding documents (:169-171) and partial flushes (:179-181), not memory that grows with every call and is never checked; the refresh-yourself advice is scoped to delete-by-Query, whose RAM "Lucene currently has no way to measure", while these bytes are measured (ReadersAndUpdates.java:161) and then never compared; the same resolved updates through the term path are bounded by exactly this rule; and the commit and issue records show no decision to exempt this path. What stays true: no public javadoc promises in so many words that tryUpdateDocValue honours the RAM buffer, so it is Low and a maintainer may call the fix an improvement.

Two options were built and run through gradle at e1faeba08bde; the others are untested ideas. Both validated options are sketches: no concurrent stress test was run. Formatting: with A, ./gradlew :lucene:core:checkGoogleJavaFormat fails on exactly one hunk, the closure re-indented under tryModifyDocument( (the check's own message says to run ./gradlew tidy); B was not format-checked.

The hunt's diff, unchanged: keep tryModifyDocument's sequence number and, when it is not -1, call writeSomeDocValuesUpdates(), so each successful call attempts the same best-effort 50% rule that runs after a packet apply (the attempt is skipped while another thread holds writeDocValuesLock and is itself writing, IndexWriter.java:808). No API change.

-    return tryModifyDocument(
+    final long seqNo =
+        tryModifyDocument(
         readerIn,
         docID,
         (leafDocId, rld) -> { ... });
+    if (seqNo != -1) {
+      // The resolved updates went straight into the reader pool: apply the same RAM rule as after
+      // applying a frozen packet, else they are only written on the next refresh or commit:
+      writeSomeDocValuesUpdates();
+    }
+    return seqNo;

Trade-offs

• Writes under the monitor. tryUpdateDocValue is synchronized, so doc-values files are written while the IndexWriter monitor is held. writeSomeDocValuesUpdates was designed to take that monitor once per segment write ("Only acquire IW lock on each write, since this is a time-consuming operation. This way other threads get a chance to run in between our writes", IndexWriter.java:842-843), and LUCENE-7868 first asserted that it runs without the monitor (the assert was removed in LUCENE-8260, 8975692953). Other threads that need the writer's monitor (for example other try-updates and tryDeleteDocument, both synchronized) wait while these files are written. No new lock-order edge that can block: the only edge A adds is the writer's monitor -> writeDocValuesLock, which is taken only with tryLock() (:808) and never waits; the monitors the method then takes (ReaderPool, the synchronized ReadersAndUpdates.writeFieldUpdates) are already taken under the writer's monitor on the packet path (synchronized (this), :844-860). No run deadlocked, but no concurrent stress test was run.
• Per-call cost. Each successful call also sums the reader pool (ReaderPool.ramBytesUsed(), synchronized, one pass over the pooled segments).
• More files. Heavy try-update streams write new doc-values generations more often instead of holding memory.
• Untested corner (a cross-model review note): the write covers only generations up to the completed delete generation (:857), so while older packets are still being applied the call may write nothing until those packets' own apply runs the rule.
• Error semantics. The update is already in the pool when writeSomeDocValuesUpdates runs, so if that write throws an IOException the caller gets an exception for an update that took effect, and a retry adds another update.

What the checks validated

• This doc (gradle, scratch worktree of e1faeba08bde, 2026-11-02): the minimal test fails on stock and passes with A, assertions on and off; TestNumericDocValuesUpdates, TestBinaryDocValuesUpdates, TestMixedDocValuesUpdates, TestSoftDeletesRetentionMergePolicy, TestSoftDeletesDirectoryReaderWrapper, TestReaderPool and TestDocValuesFieldUpdates (104 tests, 2 skipped) pass on stock and with A, assertions on (only the minimal test also ran with assertions off). The fact check re-ran the suites with A and with B under its own seeds (105 tests with the minimal test, 0 failures).
• The hunt (on 645d4fe14a20): the minimal test and 86 upstream doc-values update and soft-deletes tests pass; the bounded exhaustive check over 11,110 operation sequences finds 4,922 violations on main and 0 with A (max pending 441,548 bytes against 4,240,000); the independent reproducer's and the cross-model reviewers' tests pass with it; the 7.4.0 port passes with the same call.

Drop synchronized from tryUpdateDocValue and make the same call after tryModifyDocument returns. tryModifyDocument stays private synchronized and runs the closure under the monitor, so the update itself is serialized as before; building the update objects then runs unsynchronized, as it already does in updateDocValues(Term, ...). This matches the packet-apply call site, which also runs outside the monitor ("don't hold IW monitor lock here", IndexWriter.java:6590).

Trade-offs

Changes the locking of a public method: callers no longer hold the writer's monitor for the whole call. Otherwise as A (per-call sum, more files, the same untested corner, the same error semantics).

What the checks validated

The same gradle runs as A: the minimal test passes with B, assertions on and off, and the same 104 tests pass with assertions on. Only this doc and the fact check ran B, and it was not format-checked; the hunt's exhaustive check, its 86 upstream tests and the reviewers covered A only.

Keep one update object per segment and field and add to it, so memory grows with documents, not calls.

Trade-offs

Each call has its own delete generation, which orders it against buffered term-based updates; merging generations touches the ordering that LFV-009 (a try-update overwritten by an earlier buffered update) is about. A larger change.

Let the existing flush control see the pending updates.

Trade-offs

Broader: changes accounting for every path, not only this one.

Say in the tryUpdateDocValue javadoc that its pending updates are held until the next refresh, flush() or commit.

Trade-offs

Cheapest; leaves memory that is measured but never checked.

Method: non-formal (the first signal was a heap probe).

• The hunt swept 11 single-threaded IndexWriter workloads with the default config in a 256 MB heap and compared the heap retained after garbage collection with the 16 MB RAM buffer and IndexWriter.ramBytesUsed(). tryUpdateDocValue with a reader that is never refreshed, and its soft-delete variant, grew without bound to OutOfMemoryError; the same workload with a refresh every 10,000 calls, tryDeleteDocument and the term-based update workloads stayed bounded.
• A hunt unit reduced the lead to the one-test repro and ran a bounded exhaustive model-based check on the real jar: all 11,110 sequences of 1 to 4 operations over 10 writer operations (try numeric, binary and soft-delete bursts, term updates, tryDeleteDocument, addDocument, an automatic flush, flush(), refresh, commit), comparing the pooled segment's pending bytes after every operation with the documented rule. 4,922 sequences break it on main and 0 with the fix; an abstract model of the code predicts all 33,570 byte values exactly.