IndexWriter.forceMerge(n) can return normally with more than n segments when a merge it adopted fails

IndexWriter.forceMerge(n) adopts every merge that is already pending or running when it starts, including one its own flush has just started, and waits for it. If that merge fails, for example on a full disk, the failure is filed under an older merge generation and dropped, and the writer's other alarm, the tragic event, is raised only after the waiting call has been woken. The call can then return normally with more than n segments. A moment later the writer rolls back to the last commit and closes; the next call that changes or commits the index throws AlreadyClosedException, but close() returns normally, so forceMerge(1); close() can report success while the changes since the last commit are gone. No special configuration is needed; it needs a merge I/O failure and, since 5.3.0, a short race, so it is rare. It has been there since 2.3.0.

• Segments and merges. An index is a set of segments; merges combine segments, by default in background threads of the ConcurrentMergeScheduler. Commits, flushes and NRT reopens ask the merge policy for merges and register them as pending; a merge thread then runs them.
• forceMerge(n). "Forces merge policy to merge segments until there are <= maxNumSegments". The blocking form waits until merging finishes; its wait loop is meant to throw when merging cannot finish (its comment: "so the calling thread will know merging did not complete", :2314-2318).
• Adopted merge. A merge that is already pending or running when forceMerge starts. forceMerge marks it as part of the forced merge (maxNumSegments = n) and waits for it.
• mergeGen. A counter. Every merge is stamped with its value when it is registered; forceMerge clears its list of failed merges and increments the counter; a failure is recorded in the list only if the merge's stamp equals the counter.
• Tragic event. A failure the writer cannot recover from; since 5.3.0 every failed merge is one. The writer records it, rolls back to the last commit and closes.

1. forceMerge flushes first (:2248). The flush can register a natural merge, stamped with the current generation, say 0 (merge.mergeGen = mergeGen, :5218).
2. It then clears its failure list and bumps the generation to 1 (resetMergeExceptions(), :2250, :3039-3042), and marks every pending and running merge as forced (merge.maxNumSegments = maxNumSegments, :2258-2279). It does not update merge.mergeGen: the adopted merge keeps stamp 0.
3. The adopted merge fails. handleMergeException calls addMergeException (:5040-5041), which records it only if (... mergeGen == merge.mergeGen) (:5821): 1 is not 0, so the failure is dropped.
4. Still holding the writer lock, the merge thread calls mergeFinish, which wakes every waiter (notifyAll()) and removes the merge from the running list (:5094, :5375-5391); after a failure no follow-up forced merge is registered (:5096-5106). Only after releasing the lock does it publish the tragedy (tragicEvent, :5109-5113; comment "Important that tragicEvent is called after mergeFinish, else we hang").
5. The woken forceMerge checks the tragedy (not set yet), its failure list (empty) and whether forced merges are pending (none), breaks out of the loop (:2284-2312), passes ensureOpen() because the writer is not closed yet (:2318) and returns normally.
6. Then the tragedy is set, the writer rolls back to the last commit and closes (:6090-6106). The next call that changes or commits the index (a call guarded by ensureOpen()) throws AlreadyClosedException; close() and rollback() return normally on a closed writer (:1312-1339, :1374-1393, :2576-2584).

Before 5.3.0 merge failures were not tragic, so step 5 happened every time and the writer stayed open. A merge forceMerge registers itself gets the new stamp, so its failure is reported ("background merge hit exception"). The TLA+ model also found a second path that step 2 alone does not explain: a merge that fails and records its failure just before forceMerge clears the list, and is then adopted (model only, not run on a jar).

Deterministic JUnit on main, assertions on and off: the merge started by forceMerge's own flush, the merge started by an earlier commit() (both LogDocMergePolicy with merge factor 2) and the default TieredMergePolicy merge of 9 one-document segments all fail with the injected IOException (thrown when the merge creates a file), and forceMerge(1) returns normally with 2, 2 and 9 segments; the control throws IOException: background merge hit exception: _0(11.0.0):c1 _1(11.0.0):c1 into _2 [maxNumSegments=1]. The impact demo's close() returns normally and the index holds 1 of 2 documents. Without test points or InfoStream hooks, the public-API program returned normally in 5 and 7 of 300 runs, and earlier runs in 1/200 to 12/300; another hook-free test in 22 to 84 of 500.

• Who is hit. Callers of the blocking forceMerge(n) (forceMerge(int) or forceMerge(n, true)) while a natural merge registered by an earlier commit, flush or NRT reopen, or by forceMerge's own flush, is pending or running. A lone forceMerge(1) after uncommitted adds is enough. A writer that only opens an index and calls forceMerge(1) with no uncommitted changes, like the upgrade idiom in lucene/MIGRATE.md:178-180, is not affected: its flush registers no merge (:4378, :4403-4426), so it waits only for merges it registered itself, whose failure is reported (a probe of that idiom threw in 300 of 300 runs).
• Default or opt-in. Default: no special configuration is needed; the default ConcurrentMergeScheduler and TieredMergePolicy give 9 segments at return in the deterministic test (its writer config differs from the default only in the test hooks and a 256 MB RAM buffer). The hook-free runs used LogDocMergePolicy with merge factor 2. Not affected: SerialMergeScheduler (the merge runs in the calling thread, so its exception propagates) and forceMerge(n, false), which does not wait.
• The trigger. An I/O failure in the adopted merge, most realistically a full disk: forceMerge "requires free space that is proportional to the size of the index", 2X to 3X (IndexWriter.java:2195-2197). No other forced merge may be pending or running when the woken call checks; otherwise it waits again, normally sees the tragedy and throws.
• Consequence: a false success. forceMerge(n) returns with more than n segments, then the writer closes itself and discards every change since the last commit (adds, updates, deletes). The next call that changes or commits the index throws AlreadyClosedException with the tragedy as cause and getTragicException() returns it, but close() returns normally, so change; forceMerge(1); close() can complete without an exception while the change is gone. A hook-free probe ran "delete, or update to a restricted version; forceMerge(1); close()" back to back: every call returned normally and the old document was still live in the committed index in 1 to 17 of 500 attempts per configuration on main, 10.5.2 and 9.12.3, and in 0 of 500 with either fix; in the other attempts an exception was reported (483 to 499 of 500) or close() committed the change first (0 to 2). The default scheduler also throws MergeException in the merge thread (ConcurrentMergeScheduler.java:760-762), which by reading reaches that thread's uncaught-exception handler, by default a stack trace on stderr. Nothing is corrupted; the last commit stays intact.
• Before 5.3.0 merge failures were not tragic: optimize/forceMerge returned normally with the index unmerged every time and the writer stayed open (executed on 2.3.0 and 5.2.1).
• How often. Rare: an I/O failure in an adopted merge plus, since 5.3.0, a race the caller cannot influence (0.5% to 17% of attempts with a failing merge in small hook-free harnesses whose failure hits only the merge's own writes; not field rates). No report was found in the 11 years since 5.3.0.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected forceMerge(1) to throw because the merge of _0 and _1 it waited for failed with java.io.IOException: disk full, but it returned normally
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.assertTrue(Assert.java:42)
       org.junit.Assert.assertNotNull(Assert.java:713)
       org.apache.lucene.index.TestForceMergeAdoptedMergeFailure.testFailedMergeStartedByForceMergeFlushIsReported(TestForceMergeAdoptedMergeFailure.java:101)

• The wait loop states the intent. "Forward any exceptions in background merge threads to the current thread" (:2293-2294); a tragedy throws "this writer hit an unrecoverable error; cannot complete forceMerge" (:2286-2290); and after the loop: "If close is called while we are still running, throw an exception so the calling thread will know merging did not complete", then ensureOpen() (:2314-2318).
• The javadoc. @param maxNumSegments maximum number of segments left in the index after merging finishes (:2223); "This call will merge those segments present in the index when the call started" (:2219); @throws IOException if there is a low-level IO error (:2225). Its disk-full paragraph describes a partially merged index for the case "If an Exception is hit" (:2213-2217), that is, when the call throws.
• The control. A merge forceMerge registered itself, failing the same way, is forwarded as IOException: background merge hit exception on every version where the control ran (2.3.0, 5.2.1, 5.3.0, 9.12.3, 10.5.2 and main).
• The filter exists only for forceMerge. resetMergeExceptions() has one caller, forceMerge (:2250), and the failure list is consumed only by forceMerge's wait loop (:2292-2303; addMergeException reads it only to skip duplicates, :5821). In this scenario the merges it filters out are exactly those forceMerge has just marked as its own and waits for (maxNumSegmentsMergesPending, :2326-2336); a merge started by forceMerge's own flush cannot predate the call.
• Nothing accepts it. No javadoc, CHANGES.txt or MIGRATE.md entry, test or issue describes a normal return after a failed adopted merge; TestIndexWriterExceptions.testForceMergeExceptions and TestIndexWriterOnDiskFull tolerate exceptions but never check the segment count after a normal return.
• Precedent. LUCENE-1376 (#2450, 2008), "sometimes if a BG merge hits an exception, optimize() will fail to forward the exception", and LUCENE-2618 (#3692, 2010), an adoption gap for concurrently started natural merges, were both fixed as bugs. This case survives both fixes.

The strongest case for "intended" (from the intended-behaviour checker and the cross-model refute review): mergeGen has deliberately kept earlier merges' failures out since 2007; publishing the tragedy after mergeFinish is deliberate (LUCENE-6579); the javadoc never says every background failure reaches the caller and it allows a partial merge; the writer still reports the tragedy at the next call and in the merge thread; close() doing nothing on a closed writer matches Closeable; forceMerge(n) may legitimately leave more than n segments when a policy skips segments; and the deterministic test needs test points and an @lucene.internal InfoStream hold.

Why it fails: forceMerge reclassifies the adopted merges as its own and waits for them, and a merge started by its own flush removes any "not your merge" reading. The LUCENE-6579 comment requires only that the close follows mergeFinish; onTragicEvent only sets a field, the close is maybeCloseOnTragicEvent (:6068-6106). The partial-merge sentence is about a call that throws. A later report does not make a return correct whose postcondition is false. The 2 or 9 segments are not a policy decision: the follow-up forced merge is skipped only because the merge failed (:5096-5106). And the hook-free public-API program fails without any test point or InfoStream hook, while upstream tests already use the same test points (TestConcurrentMergeScheduler.java:1007,1014). The refute reviewer agreed with the root cause ("mechanically credible") and called its own not-real verdict procedural; it could not run code. Verdict: not intended.

Two fix sketches from the hunt, both validated through gradle in scratch worktrees of a9779ef3c193. They differ in what they cover and in which exception a waiting forceMerge gets. Present both.

+5 lines in IndexWriter.merge (IndexWriter.java:5084): call onTragicEvent in the inner catch, so the tragedy is set before mergeFinish calls notifyAll(); tragicEvent (which closes the writer) stays after mergeFinish, as LUCENE-6579 requires.

} catch (Throwable t) {
  if (t instanceof MergePolicy.MergeAbortedException == false) {
    // publish the tragedy before mergeFinish() wakes threads that wait for this merge;
    // the writer is still closed only after mergeFinish (tragicEvent below)
    onTragicEvent(t, "merge");
  }
  handleMergeException(t, merge);
}

Trade-offs

• Closes both paths in the TLA+ model: the dropped failure and the failure cleared by the reset (configs fixtrag1 4,847 states, two callers with the same n 91,094, wider bounds up to 38,896,974; invariants hold; two callers with different n still violate F1 through the separate LFV-592).
• For an ordinary failure (merge aborts are skipped by the patch) of a merge it waits for, a waiting forceMerge then throws IllegalStateException: this writer hit an unrecoverable error; cannot complete forceMerge (cause: the merge's exception) instead of, sometimes, the IOException: background merge hit exception it gets today; the control shows this change. As today, an InfoStream whose message() throws makes onTragicEvent skip setting the field (:6075-6083).
• onTragicEvent runs twice per failed merge (the second compareAndSet is a no-op, but "hit tragic" is logged twice), and other threads can see the tragedy while the merge is still in the running list; by reading, a concurrent rollback then waits in abortMerges until the merge leaves it. The suites showed no hang.
• The test's hold then sits before mergeFinish, so each fixed test waits out its 10 s bound.

What the checks validated

• Gradle, scratch worktree of a9779ef3c193 (removed afterwards), 2026-10-27: the paste-ready 4-test class and the impact demo pass with assertions on and off (forceMerge throws IllegalStateException: ... cannot complete forceMerge; pass 4), and an earlier version of the tests with tests.iters=10 (seed CAFEBABE): 50 of 50.
• 24 closest org.apache.lucene.index suites (TestIndexWriter, TestIndexWriterExceptions, TestIndexWriterExceptions2, TestIndexWriterOnDiskFull, TestIndexWriterForceMerge, TestConcurrentMergeScheduler, TestTragicIndexWriterDeadlock, TestThreadedForceMerge, TestRollback, TestAddIndexes and others): 376 tests, 0 failures, 19 skipped, with assertions on and off.
• All of :lucene:core:test (seed DEADBEEF): 750 classes, 8,894 tests, 0 failures, 0 errors, 322 skipped; :lucene:core:check -x test passes with the paste-ready tests.
• Earlier, on the jar: the hook-free program 0 of 200 normal returns; the hook-free probes 0 of 500 silent losses (delete and update modes); the finder's hooked 4-test JUnit 4 of 4.

+4 lines in the adoption loops (IndexWriter.java:2260-2278): merge.mergeGen = mergeGen; next to merge.maxNumSegments = maxNumSegments; for pending and running merges, so an adopted merge's failure reaches the wait loop like that of a merge forceMerge registered itself.

for (final MergePolicy.OneMerge merge : pendingMerges) {
  merge.maxNumSegments = maxNumSegments;
  // this call now waits for the merge: report its failure to this call
  merge.mergeGen = mergeGen;
  ...
for (final MergePolicy.OneMerge merge : runningMerges) {
  merge.maxNumSegments = maxNumSegments;
  merge.mergeGen = mergeGen;

Trade-offs

• Smallest change; adopted merges then behave exactly like merges forceMerge registers (IOException: background merge hit exception when the waiter is first, IllegalStateException when the tragedy is).
• Misses the model's second path: a merge that fails and records its failure just before forceMerge clears the list, and is adopted afterwards (config fixgen1, not run on a jar). A possible complement, untested: in the adoption loops, also add a merge whose getException() is already set to the failure list.
• Keeps the writer-wide mergeGen and failure list that concurrent forceMerge calls share: by reading, a second call's reset can still clear a failure already recorded for the first (the model's two-caller stock config two_stock_same shows that clearing; fix A was not model-checked with two callers).

What the checks validated

• Gradle, scratch worktree of a9779ef3c193 (removed afterwards), 2026-10-27: the paste-ready 4-test class and the impact demo pass with assertions on and off (forceMerge throws IOException: background merge hit exception; pass 4), and an earlier version of the tests with tests.iters=10: 50 of 50.
• The same 24 closest suites: 376 tests, 0 failures, 19 skipped, assertions on and off. All of :lucene:core:test: 750 classes, 8,894 tests, 0 failures, 322 skipped; :lucene:core:check -x test passes with the paste-ready tests.
• Earlier, on the jar: the independent reproducer's shadow fix 0 of 500 normal returns hook-free; the hook-free probes 0 of 500 silent losses.

Track the merges a forceMerge call waits for and check each one's getException() when it finishes, as MergePolicy.MergeObserver does for forceMergeDeletes, instead of the generation-filtered list; or drop the generation filter for merges that have maxNumSegments set.

Trade-offs

Larger changes to the wait protocol; not built or run.

Method: TLA+ model checking (TLC) of the forced-merge wait protocol, at the granularity of the writer's synchronized blocks (ForceMergeWait.tla), with 1-2 callers, 1-2 merge threads, a flushing thread, deleteAll and merge I/O failures as actions, and fix switches.

• The hunt unit's plan already read the mechanism from the code, so this is semi-formal, not a blind find. TLC then witnessed it: invariant F1, "a normal return leaves the segments present at the call merged into at most n", is violated by a 12-state trace (config stock1).
• TLC also found a second path that the mergeGen fix alone misses (fixgen1, a 12-state trace), and showed the tragedy-first fix clean (fixtrag1, 4,847 states; two same-target callers 91,094; wider bounds on a separate host up to 38,896,974 states). The model abstracts merge-policy choices and timed waits and does not model close(), commit() or a throwing InfoStream: it supports the wait-protocol argument, not the full safety of either patch.
• The trace was replayed on the stock jar as the JUnit (test points, MockDirectoryWrapper fault injection, an InfoStream hold). A stress test without test points or InfoStream hooks returned normally in 1/100 and 5/100 runs, and the public-API program in 2/200 and 5/200 (0/200 with a fix).
• The model's liveness check also led to two sibling bugs with NoMergeScheduler (LFV-586, LFV-587); an overlap of two forceMerge calls with different n is the separate LFV-592.