MyCATApache/Mycat-Server · error · IllegalArgumentException

Initial capacity exceeds maximum capacity of

Error message

Initial capacity ${initialCapacity} exceeds maximum capacity of ${maxCapacity}

What it means

BytesToBytesMap's constructor validates that the requested initial capacity is positive and does not exceed MAX_CAPACITY. This IllegalArgumentException is thrown when initialCapacity is greater than the map's hard maximum supported capacity, because internal sizing (to a power-of-2 long array) cannot accommodate it.

Solutions

Reduce the initialCapacity argument to a value <= BytesToBytesMap.MAX_CAPACITY (map grows internally as needed, so a modest initial capacity like 1024 or 65536 is fine).
Check the config source feeding initialCapacity (e.g. a capacity property) for unit mistakes — e.g. passing bytes or row counts of the whole dataset instead of an initial table size.
Clamp the value programmatically before constructing: `initialCapacity = Math.min(initialCapacity, BytesToBytesMap.MAX_CAPACITY)`.
If the workload genuinely needs more entries than MAX_CAPACITY, shard the data across multiple BytesToBytesMap instances.

Example fix

// before
BytesToBytesMap map = new BytesToBytesMap(
    memoryManager, allocator, 4_000_000_000L, 64 * 1024 * 1024, false);
// after
long initialCapacity = Math.min(4_000_000_000L, BytesToBytesMap.MAX_CAPACITY);
BytesToBytesMap map = new BytesToBytesMap(
    memoryManager, allocator, initialCapacity, 64 * 1024 * 1024, false);

Defensive patterns

Strategy: validation

Validate before calling

if (initialCapacity <= 0 || initialCapacity > BytesToBytesMap.MAX_CAPACITY) {
  initialCapacity = Math.min(Math.max(initialCapacity, 1), BytesToBytesMap.MAX_CAPACITY);
}
BytesToBytesMap map = new BytesToBytesMap(mm, allocator, initialCapacity, pageSize, metrics);

Try / catch

try {
  map = new BytesToBytesMap(mm, allocator, initialCapacity, pageSize, metrics);
} catch (IllegalArgumentException e) {
  map = new BytesToBytesMap(mm, allocator, BytesToBytesMap.MAX_CAPACITY, pageSize, metrics);
}

Prevention

Clamp initialCapacity against BytesToBytesMap.MAX_CAPACITY before construction.
Never wire raw dataset row counts directly as initial capacity.
Use a modest default (e.g. 1024) — the map grows internally.
Unit-test config parsing that feeds capacity values.

When it happens

Trigger: Calling `new BytesToBytesMap(memoryManager, allocator, initialCapacity, pageSizeBytes, enablePerfMetrics)` (or the other constructor overloads) with initialCapacity > BytesToBytesMap.MAX_CAPACITY.

Common situations: Configuring a Mycat memory cache/join map with a capacity copied from a large production dataset or computed from `2 * expectedRows` where expectedRows is huge; copy-pasted Spark-style tuning configs specifying multi-billion entry capacities.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of MyCATApache/Mycat-Server@65f8d8beb7 (2026-09-11). Data as JSON: /api/errors/80442c7ef522658a. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/io/mycat/memory/unsafe/map/BytesToBytesMap.java:196

      DataNodeDiskManager blockManager,
      SerializerManager serializerManager,
      int initialCapacity,
      double loadFactor,
      long pageSizeBytes,
      boolean enablePerfMetrics) {
    super(dataNodeMemoryManager, pageSizeBytes);
    this.dataNodeMemoryManager = dataNodeMemoryManager;
    this.blockManager = blockManager;
    this.serializerManager = serializerManager;
    this.loadFactor = loadFactor;
    this.loc = new Location();
    this.pageSizeBytes = pageSizeBytes;
    this.enablePerfMetrics = enablePerfMetrics;
    if (initialCapacity <= 0) {
      throw new IllegalArgumentException("Initial capacity must be greater than 0");
    }
    if (initialCapacity > MAX_CAPACITY) {
      throw new IllegalArgumentException(
        "Initial capacity " + initialCapacity + " exceeds maximum capacity of " + MAX_CAPACITY);
    }
    if (pageSizeBytes > DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES) {
      throw new IllegalArgumentException("Page size " + pageSizeBytes + " cannot exceed " +
        DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES);
    }
    allocate(initialCapacity);
  }

  public BytesToBytesMap(
      DataNodeMemoryManager dataNodeMemoryManager,
      int initialCapacity,
      long pageSizeBytes) {
    this(dataNodeMemoryManager, initialCapacity, pageSizeBytes, false);
  }

  public BytesToBytesMap(
      DataNodeMemoryManager dataNodeMemoryManager,

View on GitHub (pinned to 65f8d8beb7)