aeron-io/aeron · error · IllegalStateException

Page size not a power of 2: page size=

Error message

Page size not a power of 2: page size={pageSize}

What it means

LogBufferDescriptor.checkPageSize requires the page size to be a power of 2, since Aeron computes page alignment with shifts and masks. Any non-power-of-two page size is rejected with IllegalStateException.

Solutions

1. Round the page size to the next power of two with BitUtil.findNextPositivePowerOfTwo
2. Use canonical sizes: 4096, 8192, 16384, 65536, 1048576
3. Validate with BitUtil.isPowerOfTwo(pageSize) during configuration load

Example fix

// before
driverCtx.filePageSize(10_000);
// after
driverCtx.filePageSize(BitUtil.findNextPositivePowerOfTwo(10_000)); // 16384

if (!BitUtil.isPowerOfTwo(pageSize)) { pageSize = BitUtil.findNextPositivePowerOfTwo(pageSize); }

try { driver = MediaDriver.launch(ctx); } catch (final IllegalStateException ex) { if (ex.getMessage().startsWith("Page size not a power of 2")) { ctx.filePageSize(BitUtil.findNextPositivePowerOfTwo(ctx.filePageSize())); driver = MediaDriver.launch(ctx); } else throw ex; }

When it happens

Trigger: Passing pageSize such as 5000, 8192+1, or 1000000 to filePageSize configuration or log buffer factory methods that call checkPageSize.

Common situations: Config values derived from OS-specific defaults that are not powers of two, or user-tuned settings like file-page-size=10000.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Page size less than min size of
• Page size more than max size of
• 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/0699ff16be8c68d8. Report an issue: GitHub.

Appendix: source

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

     * @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);
    }

    /**
     * Set the initial term at which this log begins. Initial should be randomised so that stream does not get
     * reused accidentally.
     *

View on GitHub (pinned to 6d60124e15)