TieredMergePolicy accepts setMaxMergedSegmentMB(0), then commit(), close() and forceMergeDeletes() throw once enough documents are deleted

TieredMergePolicy.setMaxMergedSegmentMB rejects only negative values, so 0 is stored as a 0-byte maximum; so are -0.0, every positive value below 2^-20 MB (one byte), and NaN. The merge-selection loop in doFindMerges runs only while bytesThisMerge < maxMergedSegmentBytes, which is 0 < 0 before the first segment is added, so the loop never admits a segment, not even through the branch that turns an oversized segment into a one-segment ("singleton") merge. The candidate list stays empty, and the next lines fail: assert candidate.size() > 0 with assertions on, candidate.get(0) with IndexOutOfBoundsException with them off. This comes out of commit(), close(), NRT reopens and segment-flushing adds once more than 20% of the index and of some segment is deleted, and out of forceMergeDeletes() once a segment has more than 10% deletes (the defaults of deletesPctAllowed and forceMergeDeletesPctAllowed). A 1-byte maximum works; 7.4.0 accepted 0 without error; every release checked from 7.5.0 on fails (8 releases and main executed, the same code read in the 57 release tags 7.5.0-10.5.2 of the history clone).

• Merge candidate: the list of segments TieredMergePolicy considers merging together. doFindMerges builds one per start position and keeps the best-scoring one.
• Singleton merge: a merge of one segment into a new one, which rewrites it without its deleted documents. The class javadoc describes it, "down to 1 at once, if that one has deletions" (TieredMergePolicy.java:42-44), and the selection loop states it for a segment that alone is over the maximum: "We should never have something coming in that _cannot_ be merged, so handle singleton merges" (:559-560).

1. setMaxMergedSegmentMB (:102-109) throws only for v < 0.0 ("maxMergedSegmentMB must be >=0") and stores (long) (v * 1024 * 1024): 0, -0.0, every positive value below 2^-20 MB and NaN become maxMergedSegmentBytes = 0; negative values are rejected.
2. With a 0 maximum, findMerges sets aside every non-empty segment as too large (> maxMergedSegmentBytes / 2) unless both the index and the segment are more than deletesPctAllowed (default 20%) deleted (:381-397), then calls doFindMerges (:438). findForcedDeletesMerges passes every segment with more than forceMergeDeletesPctAllowed (default 10%) deletes (:957-963, call at :968). Both leave out segments that are already merging.
3. The candidate loop's header includes bytesThisMerge < maxMergedSegmentBytes (:539-548, clause at :546). bytesThisMerge starts at 0, so the header is 0 < 0, false, before the first segment. The body, which admits an oversized first segment as a singleton ("We should never have something coming in that _cannot_ be merged, so handle singleton merges", :552-570), never runs.
4. assert candidate.size() > 0 (:578) fails with assertions on; segInfosSizes.get(candidate.get(0)) (:580) throws IndexOutOfBoundsException with them off.
5. Callers: commit() and prepareCommit() through findFullFlushMerges (IndexWriter.java:3863 -> :2496, MergePolicy.java:693; with the default 500 ms maxFullFlushMergeWaitMillis, :3858); NRT reopens (:635, :704-706), close(), an explicit flush(), maybeMerge() and segment-flushing adds through maybeMerge (:2445 -> :2508, :6345-6360); forceMergeDeletes() (:2359), or already in its preliminary flush(true, true) (:2348) when deletes are still unflushed. The selection of forceMerge(1) (findForcedMerges, TieredMergePolicy.java:745-921) does not use doFindMerges and is not affected (executed).

A 1-byte maximum makes the header 0 < 1, so the first segment enters and becomes a singleton merge.

What it does to the writer (main ea57360912ed, the same code, and an entry-point probe on a9779ef3c193): with assertions off no entry point records a tragic event and the writer stays open; calls keep failing while the delete thresholds are exceeded (a second commit after 10 more documents threw again), and replacing the merge policy on the live config (w.getConfig().setMergePolicy(new TieredMergePolicy())) recovers it. With assertions on, commit(), prepareCommit(), NRT reopens and segment-flushing adds record the AssertionError as tragic and the writer closes (IndexWriter.java:3879-3883, :711-721, :1632-1640); forceMergeDeletes(), an explicit flush() and maybeMerge() let it propagate and the writer stays open, not tragic. A close() that throws closes the writer and drops the uncommitted changes, as close() documents for any exception (:1344-1352). With the default 500 ms maxFullFlushMergeWaitMillis a failing commit() writes no commit point: the index on disk stays at the last commit and CheckIndex is clean. With setMaxFullFlushMergeWaitMillis(0) the commit is written first (:4261) and commit() then throws from the post-commit maybeMerge (:4265-4266), so the caller sees an exception for a durable commit. An addDocument whose automatic flush throws has already been indexed, so retrying it can add a duplicate.

• Who is hit. Applications that configure the default TieredMergePolicy with a 0 maximum, or with -0.0, a positive value below 2^-20 MB or NaN. Some people set 0 meaning "no limit": one user on a downstream forum set a 0-byte maximum expecting "unlimited" (that server maps 0 to "unset", so Lucene never saw it), and Lucene's own randomized tests were steered away from 0 in 2013 and from near-0 values in 2015.
• Opt-in. A non-default value of a public setter on the default merge policy.
• Delayed. Append-only indexing works; the failure starts once update or delete churn pushes the index and a segment past deletesPctAllowed (20% by default), or when forceMergeDeletes() runs on a segment with more than forceMergeDeletesPctAllowed (10% by default) deletes.
• Effect. Commits, closes, NRT reopens and segment-flushing adds keep failing while those thresholds are exceeded. With assertions off the writer is usable again after the merge policy is replaced; with assertions on, a failing commit, NRT reopen or flushing add closes it. A throwing close() drops the uncommitted changes, as close() documents for any exception. With setMaxFullFlushMergeWaitMillis(0) a commit() that throws has already been written. No corruption of committed data, no wrong hits, no hang.
• Scale. None: 10 documents.
• Likelihood. Rare: no matching report was found in the searches (see Prior reports), eight years after 7.5.0, and the downstream wrappers seen mostly treat 0 as "unset" or reject it.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected forceMergeDeletes() to succeed, got java.lang.AssertionError
       org.apache.lucene.index.TestTieredMergePolicyZeroMaxMergedSegment.testForceMergeDeletes(TestTieredMergePolicyZeroMaxMergedSegment.java:43)
     Caused by: java.lang.AssertionError
       org.apache.lucene.index.TieredMergePolicy.doFindMerges(TieredMergePolicy.java:578)
       org.apache.lucene.index.TieredMergePolicy.findForcedDeletesMerges(TieredMergePolicy.java:968)
       org.apache.lucene.index.IndexWriter.forceMergeDeletes(IndexWriter.java:2359)
       org.apache.lucene.index.IndexWriter.forceMergeDeletes(IndexWriter.java:2425)
       org.apache.lucene.index.TestTieredMergePolicyZeroMaxMergedSegment.testForceMergeDeletes(TestTieredMergePolicyZeroMaxMergedSegment.java:41)

• Setter contract. if (v < 0.0) with "maxMergedSegmentMB must be >=0" (TieredMergePolicy.java:103-104); the javadoc (:97-101) gives no other range. setFloorSegmentMB checks v <= 0.0, "floorSegmentMB must be > 0.0" (:168-170): the class rejects 0 where it means to.
• Documented handling of oversized segments. "If a merge will produce a segment that's larger than {@link #setMaxMergedSegmentMB}, then the policy will merge fewer segments (down to 1 at once, if that one has deletions) to keep the segment size under budget" (:42-44). The loop says "We should never have something coming in that _cannot_ be merged, so handle singleton merges" (:559-560), and "We should never see an empty candidate" with assert candidate.size() > 0 (:576-578).
• Tests. TestTieredMergePolicy.testSetters (:759-793) tries 0.5, +Infinity, Long.MAX_VALUE / 1 MiB and -2.0 (rejected), not 0. The test framework randomizes setMaxMergedSegmentMB(r.nextDouble() * 100) (LuceneTestCaseParent.java:1977), a range that starts at 0 (a 0-byte draw has a probability of about 1e-8).
• History. Through 7.4.0, findMerges set every segment aside (no natural merges) and findForcedDeletesMerges ignored the maximum ("Don't enforce max merged size here"). LUCENE-7976 (7.5.0) put both on doFindMerges and added the clause; its CHANGES entry says only "TieredMergePolicy now respects maxSegmentSizeMB by default when executing findForcedMerges and findForcedDeletesMerges" (CHANGES.txt:7224-7227). None of the 124 comments on #9025 discusses a 0 maximum. Two test-only commits keep randomized tests away from such values: one from 2013 ("don't let maxMergedSegmentMB be 0.0"; "If we get TieredMP and it's maxMergedSegmentMB is 0 then this test falsely fails") suggests 0 was then known to mean "no merging" rather than an error; one from 2015 ("do not use near-zero maxMergedSegmentMB for this test!") only shows near-0 values did not suit one test. Neither documents what 0 means.

The strongest case for "intended": a 0-byte "maximum sized segment to produce" can never be met, and the class javadoc says "findForcedDeletesMerges should never produce segments greater than maxSegmentSize" (:61), so 0 has no valid output; users who want no merging should use NoMergePolicy; the >=0 check came with LUCENE-4323 (2012) along with a compound-file size setter where 0 does mean something; and the class is @lucene.experimental (:67).

Why it fails: that supports at most "reject 0 in the setter" or "no merge", not an internal AssertionError or IndexOutOfBoundsException out of commit(), close() or forceMergeDeletes(). A 1-byte maximum is just as impossible to meet and works; 0 worked through 7.4.0; "experimental" allows API changes, not crashes on an accepted value. The cross-model reviews rated the intended-behaviour argument weak; the independent reproducer, the devil's-advocate checker and the adjudication found the bug real without a rating. The cross-model fact check of this doc rated "0 is an invalid configuration" moderate and "the current exception is intended" weak.

Two fixes were built and validated in a scratch worktree at a9779ef3c193 (removed afterwards); either is reasonable, and the maintainers choose. Workaround today: use a maximum of at least 1 byte (1.0 / 1024 / 1024 MB), or NoMergePolicy if no merging is wanted. Related but separate: LFV-447 (setSegmentsPerTier(NaN) makes the next flush hang), which these fixes do not touch.

One clause in TieredMergePolicy.java:546. bytesThisMerge grows only when a segment is added (:571-573), so it is 0 while the candidate is empty, and 0 < max already holds for any positive maximum: the new clause differs only at 0. The first segment then reaches the existing singleton-merge branch (:552-570).

                 && (candidate.size() < mergeFactor || bytesThisMerge < floorSegmentBytes)
-                && bytesThisMerge < maxMergedSegmentBytes
+                // always look at the first segment: the body turns it into a singleton merge even
+                // when it alone exceeds maxMergedSegmentBytes (e.g. maxMergedSegmentMB == 0)
+                && (candidate.isEmpty() || bytesThisMerge < maxMergedSegmentBytes)
                 && (bytesThisMerge < floorSegmentBytes || docCountThisMerge <= allowedDocCount);

Trade-offs

• What 0 then means (executed): forceMergeDeletes() reclaims the deletes by singleton merges (30 of 100 deleted: maxDoc 70), like 1 byte. commit() succeeds but merges nothing (50 of 100 deleted: maxDoc 100), because findMerges passes maxMergeIsRunning = mergingBytes >= maxMergedSegmentBytes (:447), which is 0 >= 0, and too-large candidates are then skipped (:626-627). That is the 7.4.0 behaviour; a 1-byte maximum does reclaim on commit (maxDoc 50).
• A semantic choice. With this fix forceMergeDeletes() writes segments larger than a 0-byte maximum, as it already does for any maximum smaller than a deleted segment (1 byte, executed). The javadoc line "findForcedDeletesMerges should never produce segments greater than maxSegmentSize" (:61, added in 2021) is already not literal for those singleton merges, which LUCENE-7976 introduced. It is recommended here because every value that works today keeps working; if maintainers see 0 as an invalid configuration, the setter fix is at least as defensible.
• Large indexes were not tested: when the eligible segments total at least segsPerTier x max(smallest segment, floorSegmentBytes) bytes (with the defaults 128 MB or more), the tier loop (:402-413) reaches a 0 level size; the double division gives +Infinity (NaN at exactly that size), the loop stops at levelSize == maxMergedSegmentBytes (:406), and (int) allowedSegCount (:442) becomes Integer.MAX_VALUE (0 for NaN). No exception is expected there; what the fixed selection then picks was not tested (read only).
• Add a CHANGES entry under Bug Fixes; the clause is the same on the 10.x branches.

What the checks validated

• Clean scratch worktree at a9779ef3c193, gradle, seed DEADBEEF. Stock: 5 of 10 repro tests fail, assertions on and off. With the fix: the 3 repro classes (10 tests) and TestTieredMergePolicy, TestIndexWriterMergePolicy, TestIndexWriterForceMerge, TestIndexWriterMerging, TestIndexWriterDelete, TestForceMergeForever, TestSoftDeletesRetentionMergePolicy, TestUpgradeIndexMergePolicy, TestOneMergeWrappingMergePolicy and TestThreadedForceMerge: 115 tests, 12 skipped, 0 failures. Assertions off: the repro classes, TestTieredMergePolicy and TestIndexWriterMergePolicy, 48 tests, 0 failures.
• A fix-outcome check (commit and forceMergeDeletes with a 0 maximum, maxDoc and numDocs asserted) passes; checkGoogleJavaFormat, ecjLintMain and forbiddenApisMain on lucene/core pass.

if ((v > 0.0) == false) throws "maxMergedSegmentMB must be > 0.0" (also for -0.0 and NaN), and Math.max(1L, (long) v) rounds tiny positive values up to 1 byte; the javadoc states the range.

if ((v > 0.0) == false) { // also rejects NaN
  throw new IllegalArgumentException("maxMergedSegmentMB must be > 0.0 (got " + v + ")");
}
v *= 1024 * 1024;
maxMergedSegmentBytes = v > Long.MAX_VALUE ? Long.MAX_VALUE : Math.max(1L, (long) v);

Trade-offs

Matches setFloorSegmentMB and fails at configuration time, not at the first heavily deleted commit. A behaviour change: applications that pass 0 and index append-only, which works today, get an IllegalArgumentException, so it needs a CHANGES (maybe MIGRATE) entry. The independent reproducer's TestTMPZeroMaxMergedV1 asserts that 0 is accepted and does not fit this option.

What the checks validated

Same worktree: the finder's test (2 of 2; it returns early), a setter check (0, -0.0 and NaN rejected; 1e-7 stored as 1 byte), TestTieredMergePolicy and TestIndexWriterMergePolicy: 42 tests, 0 failures.

The loop fix keeps merge selection safe if a 0-byte maximum ever reaches it again (defence in depth: maxMergedSegmentBytes is private, so today only the setter sets it); the setter fix makes the contract explicit.

Trade-offs

Not run together; each part was validated on its own.

Map 0 to Long.MAX_VALUE in the setter.

Trade-offs

Silently changes what the value means; Lucene never documented that meaning.

Method: boundary-value testing guided by a static guard inventory (semi-formal; no model checker or prover was involved).

• A bytecode pass over 27 core and non-sandbox module jars listed 1,231 public entry points that can throw IllegalArgumentException, with each guard's parameters and constants.
• From the guard constants it derived boundary values and probed them on the real jar: setMaxMergedSegmentMB accepts 0, -0.0, Double.MIN_VALUE, 1e-7 and NaN.
• A sweep drove selected numeric setters of four merge policies (TieredMergePolicy, LogByteSizeMergePolicy, LogDocMergePolicy, TemporalMergePolicy) end to end with a watchdog (272 configurations) and flagged a thrown IndexOutOfBoundsException for every maxMergedSegmentMB value that maps to 0 bytes; 1.0 and larger were clean. Its workload deletes while indexing and calls commit() before forceMergeDeletes(), and the first exception ends a run, so with 0 the sweep did not get to forceMergeDeletes() on its own (from reading the workload); the finder's public-API JUnit then showed that path as well.