MyCATApache/Mycat-Server · error · IllegalArgumentException

Page size cannot exceed

Error message

Page size ${pageSizeBytes} cannot exceed ${maxPageSizeBytes}

What it means

BytesToBytesMap's constructor validates that pageSizeBytes does not exceed DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES. Pages are allocated as contiguous memory blocks, so a page larger than the maximum supported size cannot be allocated and the constructor fails fast with an IllegalArgumentException.

Solutions

1. Lower pageSizeBytes to at most DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES (typically tens of MB is sufficient).
2. Check the config property supplying the page size for unit conversion mistakes.
3. Clamp before construction: `pageSizeBytes = Math.min(pageSizeBytes, DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES)`.
4. If larger per-record storage is needed, increase the number of pages rather than the page size.

Example fix

// before
BytesToBytesMap map = new BytesToBytesMap(
    memoryManager, allocator, 1024, 4L * 1024 * 1024 * 1024, false); // 4GB page
// after
long pageSizeBytes = Math.min(4L * 1024 * 1024 * 1024,
    DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES);
BytesToBytesMap map = new BytesToBytesMap(
    memoryManager, allocator, 1024, pageSizeBytes, false);

if (pageSizeBytes > DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES) {
  pageSizeBytes = DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES;
}
BytesToBytesMap map = new BytesToBytesMap(mm, allocator, initialCapacity, pageSizeBytes, metrics);

try {
  map = new BytesToBytesMap(mm, allocator, initialCapacity, pageSizeBytes, metrics);
} catch (IllegalArgumentException e) {
  map = new BytesToBytesMap(mm, allocator, initialCapacity,
      DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES, metrics);
}

When it happens

Trigger: Calling `new BytesToBytesMap(...)` with a pageSizeBytes argument greater than DataNodeMemoryManager.MAXIMUM_PAGE_SIZE_BYTES.

Common situations: Tuning a page-size config value to something like 2GB or a machine's full RAM assuming larger pages are always better; unit mistakes (writing bytes where MB was intended, e.g. 17179869184 instead of 16MB).

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

• Initial capacity exceeds maximum capacity of
• Cannot allocate a page with more than
• bufferSize must not be less than 1
• bufferSize must be a power of 2
• Fractional values are not supported. Input was

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

Appendix: source

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

      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,
      int initialCapacity,
      long pageSizeBytes,
      boolean enablePerfMetrics) {
    this(

View on GitHub (pinned to 65f8d8beb7)