aeron-io/aeron · error · ConfigurationException

reserved session range too large

Error message

reserved session range too large

What it means

After checking that low <= high, Configuration.validateSessionIdRange also enforces that the size of the reserved session id range, (long)high - low, does not exceed Integer.MAX_VALUE, because the driver allocates session ids as ints within this range. Exceeding it makes the range unrepresentable, so a ConfigurationException is thrown.

Solutions

  1. Narrow the reserved range to at most 2^31 - 1 ids, e.g. low=0, high=2000000000
  2. Split usage: use a smaller auto-assignment range and explicit session ids for special streams
  3. If full-space coverage is truly needed, manage session ids outside the driver's reserved-range mechanism

Example fix

// before
Configuration.validateSessionIdRange(Integer.MIN_VALUE, Integer.MAX_VALUE);
// after
Configuration.validateSessionIdRange(0, Integer.MAX_VALUE - 1); // range <= Integer.MAX_VALUE
Defensive patterns

Strategy: validation

Validate before calling

long range = (long) high - low;
if (range > Integer.MAX_VALUE) {
    throw new IllegalStateException("reserved session range must be <= " + Integer.MAX_VALUE);
}
io.aeron.driver.Configuration.validateSessionIdRange(low, high);

Try / catch

try {
    Configuration.validateSessionIdRange(low, high);
} catch (ConfigurationException e) {
    if (e.getMessage().contains("too large")) {
        // narrow the range
        Configuration.validateSessionIdRange(low, (int)Math.min((long)low + Integer.MAX_VALUE, high & 0xFFFFFFFFL));
    } else { throw e; }
}

Prevention

When it happens

Trigger: Calling Configuration.validateSessionIdRange(low, high) where Math.abs((long)high - low) > Integer.MAX_VALUE, e.g. low = -2000000000 and high = 2000000000 (range of 4e9 > 2^31-1).

Common situations: Reserving nearly the entire int session id space (low=Integer.MIN_VALUE, high=Integer.MAX_VALUE); wide defaults copied from custom setups; combining user-defined ids with an overly broad auto-assignment range.

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

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

Appendix: source

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

    }

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

    /**
     * Validate that the timeouts for unblocking publications from a client are valid.
     *

View on GitHub (pinned to 6d60124e15)