RamUsageEstimator.sizeOfCollection adds the backing-array bytes in int arithmetic, so collections of 536,870,908 or more elements are estimated 4 GiB or more too small (negative for a list of nulls)

RamUsageEstimator.sizeOfCollection estimates a collection's heap size as the collection object, plus one array of references, plus each element's estimate. It adds the array part as NUM_BYTES_ARRAY_HEADER + collection.size() * NUM_BYTES_OBJECT_REF (RamUsageEstimator.java:307), where both constants and Collection.size() are int, so the sum is computed in 32-bit arithmetic and only then widened to long. From 536,870,908 elements on (2^29 - 4, with 4-byte references and a 16-byte array header; 268,435,453 with 8-byte references and a 24-byte header; both with the default 8-byte object alignment) it wraps. sizeOfCollection(Arrays.asList(new Object[536870908])) returns -2,147,483,616 bytes, while shallowSizeOf of the backing array correctly returns 2,147,483,648.

The estimate is then always too small by a multiple of 4 GiB (with 4-byte references 8 GiB from 1,610,612,732 elements on; up to 16 GiB with 8-byte references), and it is negative only when the elements add little: with Integer elements it is positive but 40% low at the threshold. sizeOfObject on a collection and sizeOfMap on a map with collection values reach the same line. Every other array formula in the class widens to long first. With default settings no Lucene code path sizes a collection that large (the sandbox CoveringQuery would, but only after the application raises the clause limit from 1024 to more than 536,870,907), so in practice only callers of this @lucene.internal helper, typically downstream memory accounting, are affected. It is in every release since 8.2.0 (2019) and on main; the one-line cast (long) collection.size() * NUM_BYTES_OBJECT_REF fixes it and passes Lucene's core tests.

private static long sizeOfCollection(Collection<?> collection, int depth, long defSize) {   // RamUsageEstimator.java:298
  if (collection == null) {
    return 0;
  }
  long size = shallowSizeOf(collection);                                                   // :302
  if (depth > MAX_DEPTH) {
    return size;
  }
  // assume array-backed collection and add per-object references                         // :306
  size += NUM_BYTES_ARRAY_HEADER + collection.size() * NUM_BYTES_OBJECT_REF;               // :307, all int
  for (Object o : collection) {
    size += sizeOfObject(o, depth, defSize);
  }
  return alignObjectSize(size);                                                            // :311
}

The same class sizes the same array correctly in shallowSizeOf(Object[]):

return alignObjectSize(
    (long) NUM_BYTES_ARRAY_HEADER + (long) NUM_BYTES_OBJECT_REF * arr.length);             // :512-513

1. shallowSizeOf(list) = 24 bytes (:302).
2. :307, in int: 16 + 536,870,908 × 4 = 2,147,483,648. That is one more than Integer.MAX_VALUE, so it wraps to -2,147,483,648, and size = 24 - 2,147,483,648 = -2,147,483,624.
3. The elements are null and add 0.
4. alignObjectSize rounds with Java's %, which keeps the sign, so the negative sum moves 8 bytes toward zero: -2,147,483,616.

With 536,870,907 elements the sum is 2,147,483,644, which fits, and the result is the correct 2,147,483,672. Adding one null element drops the estimate by 4,294,967,288 bytes (2^32 - 8).

• Threshold. (2^31 - 1 - header) / ref + 1: 536,870,908 = 2^29 - 4 with 4-byte references and a 16-byte header, 268,435,453 with 8-byte references and a 24-byte header (:129, :133; both with the default 8-byte object alignment). The header addition overflows first. For these two layouts a Z3 bit-vector model of the line found these minimal sizes and proved that no smaller size overflows.
• Size of the error. Always a multiple of 2^32 bytes before alignment (2^32 - 8 after it where the result is negative). With 4-byte references it is 4 GiB from 536,870,908 to 1,610,612,731 elements and 8 GiB from 1,610,612,732 on (nCopies(Integer.MAX_VALUE, null) gives 40 bytes instead of 8,589,934,632). With 8-byte references it reaches 16 GiB (48 bytes instead of 17,179,869,232 at Integer.MAX_VALUE).
• Negative only sometimes. With null elements (4-byte references) the result is negative in two ranges: from 536,870,908 to 1,073,741,810 elements, and again from 1,610,612,732 to 2,147,483,634, where the int sum wraps a second time. In between it is positive but 4 GiB low (it climbs from 0 back to 2,147,483,672); above the second range it is 0 to 40 bytes, 8 GiB low. With real elements it is usually positive but 4 GiB low: about 3% of the total with the default 256-byte size for unknown objects, 40-50% with shared Integer elements at the threshold (20-25% further up). A "not negative" check alone misses most cases.
• Entry points. Both public sizeOfCollection overloads (:285, :294); sizeOfObject on a Collection (:393, :403, the Collection case at :434); a collection value in a map passed to the public sizeOfMap (:247, :256, via :275). The hppc *ObjectHashMap.ramBytesUsed methods do not reach it: they pass the iteration cursor, not the value, to sizeOfObject (IntObjectHashMap.java:446-447).
• Not affected. sizeOfMap's own sums (:269-277), shallowSizeOf(Object[]) (:511-514) and shallowSizeOfArray (:561-574) add in long. Of the file's 16 multiplications (on 15 lines), :307 is the only one done in int.

• Who. Code that passes one huge collection to sizeOfCollection, sizeOfObject or (as a map value) sizeOfMap. RamUsageEstimator is public and @lucene.internal; downstream projects use it for memory accounting. A read-only code search found sizeOfCollection call sites in 26 files of one downstream search engine, among them a query circuit breaker (read, not run).
• Not Lucene itself, by default. No in-tree production code calls sizeOfCollection directly. The only in-tree caller that passes a Collection is the sandbox CoveringQuery (sizeOfObject(queries, ...), CoveringQuery.java:82-85), whose constructor rejects more than IndexSearcher.getMaxClauseCount() sub-queries (:70-72; default 1024). The limit is the application's to set: IndexSearcher.setMaxClauseCount(int) is public and accepts any value of at least 1, so an application that raises it above 536,870,907 and passes that many sub-queries does reach the line. No query parser builds a CoveringQuery. The other callers pass arrays, maps whose values are not collections, or scalars.
• Default vs opt-in. No setting is involved, apart from that clause limit. The threshold depends only on the JVM's object layout: the reference size and the array header, which the class derives from the reference size and the object alignment. With the default 8-byte alignment it is 536,870,908 with compressed references and 268,435,453 with 8-byte references (-XX:-UseCompressedOops, or heaps too large for compressed references). A non-default -XX:ObjectAlignmentInBytes can change the header (for example 32 bytes with 8-byte references and 16-byte alignment, which gives 268,435,452, by arithmetic); the test computes n from the runtime constants.
• Scale. Either threshold is 2 GiB of references in one collection.
• Effect. A memory budget that sums these estimates under-counts by 4 GiB (at most 8 or 16 GiB) and trips later than intended. Nothing in Lucene uses the value to decide matching, filtering, deletions or what is written. With compressed references, elements of 28 bytes or more push the correct estimate to about 16 GiB before the threshold, so a budget of half the heap trips first (executed probe).
• Likelihood: contrived (a judgement). It takes one collection with 2 GiB of references, sized by this estimator, and no default Lucene path builds or sizes one; accidental triggering looks unlikely.

• Why nCopies. It is a virtual list, so the test needs no heap beyond the default; the method still iterates the 536,870,908 nulls (about 5 s). The stronger, contract-based form compares sizeOfCollection(Arrays.asList(backing)) with shallowSizeOf(backing) (-2,147,483,616 against 2,147,483,648), but it needs a 2 GiB array (-Xmx4g). The virtual list holds no backing array, so for nCopies the "expected" size is the method's own array model, not memory the list retains; the Arrays.asList comparison is the stronger demonstration.
• Smallest input. n is computed from the runtime constants, so it is the smallest failing size on any JVM layout: with the default 8-byte alignment 536,870,908 with compressed references, 268,435,453 with -XX:-UseCompressedOops (then: expected >= 0, got -2147483608). 536,870,907 gives the correct 2,147,483,672.
• As the regression test: this same test, for example as a method of TestRamUsageEstimator. It passes with the fix.

cp $REPRO/TestRamUsageEstimatorLargeCollection.java $LUCENE/lucene/core/src/test/org/apache/lucene/util/
cd $LUCENE
./gradlew :lucene:core:test --tests org.apache.lucene.util.TestRamUsageEstimatorLargeCollection -Ptests.seed=DEADBEEF
# assertions off: add -Ptests.asserts=false (same result)

# gradle, main 645d4fe14a20, seed DEADBEEF, assertions on (the same with -Ptests.asserts=false)
TestRamUsageEstimatorLargeCollection > testSizeOfLargeCollectionIsNotNegative FAILED
    java.lang.AssertionError: sizeOfCollection of 536870908 elements: expected >= 0, got -2147483616
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:C88601A39A7659BE]:0)
        at org.junit.Assert.fail(Assert.java:89)
        at org.junit.Assert.assertTrue(Assert.java:42)
        at org.apache.lucene.util.TestRamUsageEstimatorLargeCollection.testSizeOfLargeCollectionIsNotNegative(TestRamUsageEstimatorLargeCollection.java:31)
:lucene:core:test (FAILURE): 1 test, 1  failure

# 10.6.0 (Maven Central jar), assertions on and off
java.lang.AssertionError: sizeOfCollection of 536870908 elements: expected >= 0, got -2147483616

# main 645d4fe14a20, -XX:-UseCompressedOops (8-byte references), assertions off
java.lang.AssertionError: sizeOfCollection of 268435453 elements: expected >= 0, got -2147483608

# with the fix, assertions on and off
:lucene:core:test (SUCCESS): 1 test

# the finder's array-backed tests, main ea57360912ed, -Xmx4g, assertions off
sizeOfCollection(536870908 elements) = -2147483616, but the backing Object[] alone is 2147483648 bytes
sizeOfObject(list of 536870908) = -2147483616 < backing array 2147483648

• The contract. Both public overloads: "Returns the size in bytes of a Collection object, including sizes of its values" (RamUsageEstimator.java:281, :290), with no size limit. The comment above the line says the method models an array-backed collection (:306). 536,870,908 is a legal array length; the finder's test allocated it.
• The class gets the same array right elsewhere. shallowSizeOf(Object[]) (:511-514) and shallowSizeOfArray (:561-574) cast to long before multiplying. Those casts came in with LUCENE-3867 (#4940, 2012), because the array formulas "can overflow if arrays are greater than 2 GB".
• History shows no intent. The line came in with the LUCENE-8855 follow-up 7989a863faad "Fix some size estimates and relax test assertions to work under different JVMs." (2019), which replaced the constant NUM_BYTES_ARRAY_HEADER * 2 with the element-count term. Neither the commit nor the LUCENE-8855 discussion (#9898) mentions a size limit.
• Tests. The only collection test, TestRamUsageEstimator.testCollection (:165-181), uses a 102-element list and accepts a 10% error (:174). No test or javadoc sets a size limit.

The intended-behaviour checker built the strongest case for "not a bug": RamUsageEstimator is @lucene.internal; its class javadoc says the measurements "may be slightly wrong" and sizeOfObject is a "Best effort attempt"; the array-backed model is itself a heuristic; no Lucene code reaches the size; and with the default 256-byte element size the error is only about 3%.

Why it fails: @lucene.internal is about API stability ("might change in incompatible ways in the next release"), not a waiver for wrong results, and the methods are public and documented without a size limit. "May be slightly wrong" is the class javadoc's caveat for a non-OpenJDK/Oracle-based JVM, that is, for layout assumptions, and "Best effort attempt" describes sizing objects of undetermined type, which fall back to a default size; neither covers wraparound. Here the method gets its own array formula wrong, on HotSpot, by a multiple of 2^32. A negative byte count is never a valid estimate, and with shared Integer elements the error is 40-50% at the threshold, outside the 10% that testCollection accepts. What the argument does establish: priority is low, and "no Lucene code reaches the size" holds only with the default clause limit.

Three options; option A was applied in a scratch worktree of main 645d4fe14a20 and run against the minimal test, the closest suites, all core tests and core's static checks.

One line in sizeOfCollection (RamUsageEstimator.java:307). (long) collection.size() * NUM_BYTES_OBJECT_REF is at most (2^31 - 1) × 8, far inside long, and the header is then added in long. Below the threshold the int expression was exact, so no existing estimate moves.

     // assume array-backed collection and add per-object references
-    size += NUM_BYTES_ARRAY_HEADER + collection.size() * NUM_BYTES_OBJECT_REF;
+    size += NUM_BYTES_ARRAY_HEADER + (long) collection.size() * NUM_BYTES_OBJECT_REF;

Trade-offs

None found: sizeOfCollection is not on a search hot path, and one widening costs nothing next to the per-element loop.

What the checks validated

• The minimal test passes with assertions on and off (gradle, scratch worktree of 645d4fe14a20; also standalone).
• Closest suites, seed DEADBEEF: TestRamUsageEstimator, the minimal test, the 15 hppc collection and map test classes and TestLRUQueryCache, 482 tests (4 skipped), 0 failures; sandbox TestCoveringQuery, 5 tests (2 skipped), 0 failures.
• All of :lucene:core:test passes (random seed, 8,898 tests, 321 skipped, 0 failures, the minimal test included).
• :lucene:core:check -x test passes (formatting, ecj lint, forbidden APIs, license checks).
• Earlier, on main ea57360912ed: the finder's 3 tests, an independent verifier's 4 tests (with 4-byte and 8-byte references) and a boundary check at every size pass with the same cast.

size += alignObjectSize((long) NUM_BYTES_ARRAY_HEADER + (long) NUM_BYTES_OBJECT_REF * collection.size()); also aligns the modelled array on its own, as a real array is.

Trade-offs

More faithful, but with 4-byte references it can raise the estimate of a collection with an odd number of elements by up to 8 bytes: a behaviour change beyond the bug. Not validated.

Clamp a negative estimate, or use Math.multiplyExact / Math.addExact.

Trade-offs

Not recommended: a clamp misses the more common positive-but-4 GiB-low case, and an exception from an estimator breaks callers that only want a number. Not validated.

• The hunt unit covered numeric, string and version utilities; the finder was modelling RamUsageEstimator for a no-throw property.
• Its inventory of the file's 16 multiplications (on 15 lines) showed :307 as the only one evaluated in int; the others multiply in long.
• A Z3 32-bit bit-vector model of NUM_BYTES_ARRAY_HEADER + n * NUM_BYTES_OBJECT_REF gave the minimal overflowing n: 536,870,908 for 4-byte references and a 16-byte header, 268,435,453 for 8-byte references and a 24-byte header; below each, the expression is exact (unsat). Both sizes are legal array lengths.
• A public-API JUnit test on the stock main build then failed: Arrays.asList(new Object[536870908]) sized at -2,147,483,616 bytes against 2,147,483,648 for its backing array. Independent verifiers reproduced it with their own tests, corrected the wording (the threshold is 2^29 - 4; the result is not always negative) and found no sign that it is intended.