aeron-io/aeron · error · IllegalStateException

Page size more than max size of

Error message

Page size more than max size of {PAGE_MAX_SIZE}: page size={pageSize}

What it means

LogBufferDescriptor.checkPageSize enforces that the page size does not exceed PAGE_MAX_SIZE (1GB). A pageSize above that cap is rejected with IllegalStateException because log buffer files and offset arithmetic assume bounded page sizes.

Solutions

1. Reduce filePageSize to at most 1073741824 (PAGE_MAX_SIZE)
2. Prefer typical values like 4096–1MB unless profiling shows a need for larger pages
3. Guard configuration parsing with pageSize <= LogBufferDescriptor.PAGE_MAX_SIZE before applying it

Example fix

// before
driverCtx.filePageSize(2L * 1024 * 1024 * 1024);
// after
driverCtx.filePageSize(1024 * 1024); // 1MB, within PAGE_MAX_SIZE

if (pageSize > LogBufferDescriptor.PAGE_MAX_SIZE) { pageSize = LogBufferDescriptor.PAGE_MAX_SIZE; }

try { driver = MediaDriver.launch(ctx); } catch (final IllegalStateException ex) { if (ex.getMessage().contains("Page size more than max")) { ctx.filePageSize(LogBufferDescriptor.PAGE_MAX_SIZE); driver = MediaDriver.launch(ctx); } else throw ex; }

When it happens

Trigger: Configuring filePageSize in the media driver context or channel term parameters with a value greater than 1073741824 bytes; passing such a value directly to checkPageSize.

Common situations: Attempting to optimize large-file I/O by inflating page size to 2GB/4GB, or unit mistakes in generated configuration (bytes vs GB).

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

• Page size less than min size of
• Page size not a power of 2: page size=
• filePageSize not a power of 2
• segment file length not a power of 2
• segment file length not in valid range

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/cb2745e2fa97b70f. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java:488

    }

    /**
     * Check that page size is valid and alignment is valid.
     *
     * @param pageSize to be checked.
     * @throws IllegalStateException if the size is not as expected.
     */
    public static void checkPageSize(final int pageSize)
    {
        if (pageSize < PAGE_MIN_SIZE)
        {
            throw new IllegalStateException(
                "Page size less than min size of " + PAGE_MIN_SIZE + ": page size=" + pageSize);
        }

        if (pageSize > PAGE_MAX_SIZE)
        {
            throw new IllegalStateException(
                "Page size more than max size of " + PAGE_MAX_SIZE + ": page size=" + pageSize);
        }

        if (!BitUtil.isPowerOfTwo(pageSize))
        {
            throw new IllegalStateException("Page size not a power of 2: page size=" + pageSize);
        }
    }

    /**
     * Get the value of the initial Term id used for this log.
     *
     * @param metadataBuffer containing the meta data.
     * @return the value of the initial Term id used for this log.
     */
    public static int initialTermId(final UnsafeBuffer metadataBuffer)
    {
        return metadataBuffer.getInt(LOG_INITIAL_TERM_ID_OFFSET);

View on GitHub (pinned to 6d60124e15)