aeron-io/aeron · error · ConfigurationException

low session id value

Error message

low session id value ${low} must be <= high value ${high}

What it means

Configuration.validateSessionIdRange validates the low/high bounds of the reserved session-id range used when the driver assigns session ids. It throws this ConfigurationException if the low bound is greater than the high bound, since the range would be empty/inverted. This prevents downstream session id generation from behaving nonsensically.

Solutions

1. Swap the values so low <= high in the configuration (aeron.session.id.range.low / aeron.session.id.range.high)
2. If computed programmatically, sort with Math.min/max before validating
3. Review the config source for swapped variable names

Example fix

// before
ctx.sessionIdRange(500, 100);
// after
ctx.sessionIdRange(100, 500); // low <= high

int low = Integer.getInteger("aeron.session.id.range.low", 0);
int high = Integer.getInteger("aeron.session.id.range.high", Integer.MAX_VALUE);
if (low > high) { int t = low; low = high; high = t; }
io.aeron.driver.Configuration.validateSessionIdRange(low, high);

try {
    Configuration.validateSessionIdRange(low, high);
} catch (ConfigurationException e) {
    Configuration.validateSessionIdRange(Math.min(low, high), Math.max(low, high));
}

When it happens

Trigger: Calling Configuration.validateSessionIdRange(low, high) with low > high, e.g. configuring aeron.session.id.range.low=500 and aeron.session.id.range.high=100.

Common situations: Swapping the low/high properties by mistake; constructing the range programmatically from min/max where the inputs arrive sorted incorrectly; copy-paste errors in driver configuration files.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• segment file length not a power of 2
• segment file length not in valid range
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• difference greater than 2^31 - 1: termId=
• termOffset= > termLength=

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

Appendix: source

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

        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)
        {
            throw new ConfigurationException("reserved session range too large");
        }
    }

    /**
     * Compute the length of the {@link org.agrona.concurrent.status.CountersManager} metadata buffer based on the
     * length of the counters value buffer length.
     *
     * @param counterValuesBufferLength to compute the metadata buffer length from as a ratio.
     * @return the length that should be used for the metadata buffer for counters.
     */
    public static int countersMetadataBufferLength(final int counterValuesBufferLength)
    {
        return counterValuesBufferLength * (CountersReader.METADATA_LENGTH / CountersReader.COUNTER_LENGTH);

View on GitHub (pinned to 6d60124e15)