aeron-io/aeron · error · ConfigurationException

filePageSize not a power of 2

Error message

filePageSize not a power of 2: ${pageSize}

What it means

Aeron maps term buffers and log files in fixed-size pages, so the file page size must be a power of two (and within PAGE_MIN_SIZE..PAGE_MAX_SIZE, 64KB..1GB by default). Configuration.validatePageSize throws this ConfigurationException when BitUtil.isPowerOfTwo(pageSize) is false. Non-power-of-two pages would break the bit-mask based page index arithmetic used throughout the log buffer code.

Solutions

1. Set aeron.file.page.size (or ctx.filePageSize) to a power of two, e.g. 1 << 20 (1MB) or 4MB
2. Use BitUtil.findNextPositivePowerOfTwo(desired) to round the value before setting it
3. Keep the value within PAGE_MIN_SIZE (64KB) and PAGE_MAX_SIZE (1GB)

Example fix

// before
ctx.filePageSize(3 * 1024 * 1024);
// after
ctx.filePageSize(1 << 22); // 4MB, power of two

int pageSize = Integer.getInteger("aeron.file.page.size", 1 << 20);
if (Integer.bitCount(pageSize) != 1) {
    pageSize = Integer.highestOneBit(pageSize) << 1; // round up to power of two
}
io.aeron.driver.Configuration.validatePageSize(pageSize);

try {
    ctx.filePageSize(requested);
    ctx.conclude();
} catch (ConfigurationException e) {
    ctx.filePageSize(1 << 20); // default 1MB
    ctx.conclude();
}

When it happens

Trigger: Calling Configuration.validatePageSize (via DriverContext.filePageSize / LogBufferAddressManager use) with a value like 100000, 3MB, or any non-2^N value, or a value outside the allowed min/max range.

Common situations: Trying to match a filesystem or device block size that is not a power of two; hand-computing '4MB-ish' values; misunit conversions (e.g. 10485760 for '10MB').

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
• Page size not a power of 2: page size=
• 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/7951ac59106a129e. Report an issue: GitHub.

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/Configuration.java:2549

            throw new ConfigurationException(
                "initialWindowLength=" + ctx.initialWindowLength() + " > SO_RCVBUF=" + soRcvBuf +
                ", increase " + SOCKET_RCVBUF_LENGTH_PROP_NAME + " limits to match initialWindowLength");
        }
    }

    /**
     * Validate that page size is valid and alignment is valid.
     *
     * @param pageSize to be checked.
     * @throws ConfigurationException if the size is not as expected.
     */
    public static void validatePageSize(final int pageSize)
    {
        validateValueRange(pageSize, PAGE_MIN_SIZE, PAGE_MAX_SIZE, "filePageSize");

        if (!BitUtil.isPowerOfTwo(pageSize))
        {
            throw new ConfigurationException("filePageSize not a power of 2: " + pageSize);
        }
    }

    /**
     * Validate the range of session ids based on a high and low value provided which accounts for the values wrapping.
     *
     * @param low  value in the range.
     * @param high value in the range.
     * @throws ConfigurationException if the values are not valid.
     */
    public static void validateSessionIdRange(final int low, final int high)
    {
        if (low > high)
        {
            throw new ConfigurationException("low session id value " + low + " must be <= high value " + high);
        }

        if (Math.abs((long)high - low) > Integer.MAX_VALUE)

View on GitHub (pinned to 6d60124e15)