aeron-io/aeron · error · IllegalStateException

Page size less than min size of

Error message

Page size less than min size of {PAGE_MIN_SIZE}: page size={pageSize}

What it means

LogBufferDescriptor.checkPageSize validates the file page size used for log buffers. This error means the supplied pageSize is smaller than PAGE_MIN_SIZE (4096 bytes), below what the OS mapping and Aeron's log layout assume. It is thrown as IllegalStateException during log buffer creation or when configuring the driver/media context.

Solutions

1. Set filePageSize to at least 4096 (PAGE_MIN_SIZE), e.g. context.filePageSize(4096)
2. Use the common default of 4096 or a larger power of two (e.g. 65536) if file I/O granularity warrants it
3. Validate configured page size against LogBufferDescriptor.PAGE_MIN_SIZE at startup

Example fix

// before
ctx.filePageSize(1024);
// after
ctx.filePageSize(4096); // >= LogBufferDescriptor.PAGE_MIN_SIZE

if (pageSize < LogBufferDescriptor.PAGE_MIN_SIZE) { pageSize = LogBufferDescriptor.PAGE_MIN_SIZE; }

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

When it happens

Trigger: Setting filePageSize (Aeron.Context or media driver context) to a value below 4096, e.g. file-page-size=1024, or passing a small page size directly to checkPageSize/log buffer factory code.

Common situations: Trying to reduce memory footprint by shrinking page size, misreading page-size units (bytes vs KB), or copying driver config tuned for another system.

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 more than max 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/1d1fe57122a1646d. Report an issue: GitHub.

Appendix: source

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

        }

        if (!BitUtil.isPowerOfTwo(termLength))
        {
            throw new IllegalStateException("Term length not a power of 2: length=" + termLength);
        }
    }

    /**
     * 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.
     *

View on GitHub (pinned to 6d60124e15)