{"record":{"id":"1df9a0909f3d5455","repo":"aeron-io/aeron","slug":"reserved-session-range-too-large","errorCode":null,"errorMessage":"reserved session range too large","messagePattern":"reserved session range too large","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/Configuration.java","lineNumber":2569,"sourceCode":"    }\n\n    /**\n     * Validate the range of session ids based on a high and low value provided which accounts for the values wrapping.\n     *\n     * @param low  value in the range.\n     * @param high value in the range.\n     * @throws ConfigurationException if the values are not valid.\n     */\n    public static void validateSessionIdRange(final int low, final int high)\n    {\n        if (low > high)\n        {\n            throw new ConfigurationException(\"low session id value \" + low + \" must be <= high value \" + high);\n        }\n\n        if (Math.abs((long)high - low) > Integer.MAX_VALUE)\n        {\n            throw new ConfigurationException(\"reserved session range too large\");\n        }\n    }\n\n    /**\n     * Compute the length of the {@link org.agrona.concurrent.status.CountersManager} metadata buffer based on the\n     * length of the counters value buffer length.\n     *\n     * @param counterValuesBufferLength to compute the metadata buffer length from as a ratio.\n     * @return the length that should be used for the metadata buffer for counters.\n     */\n    public static int countersMetadataBufferLength(final int counterValuesBufferLength)\n    {\n        return counterValuesBufferLength * (CountersReader.METADATA_LENGTH / CountersReader.COUNTER_LENGTH);\n    }\n\n    /**\n     * Validate that the timeouts for unblocking publications from a client are valid.\n     *","sourceCodeStart":2551,"sourceCodeEnd":2587,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/Configuration.java#L2551-L2587","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Narrow the reserved range to at most 2^31 - 1 ids, e.g. low=0, high=2000000000","Split usage: use a smaller auto-assignment range and explicit session ids for special streams","If full-space coverage is truly needed, manage session ids outside the driver's reserved-range mechanism"],"exampleFix":"// before\nConfiguration.validateSessionIdRange(Integer.MIN_VALUE, Integer.MAX_VALUE);\n// after\nConfiguration.validateSessionIdRange(0, Integer.MAX_VALUE - 1); // range <= Integer.MAX_VALUE","handlingStrategy":"validation","validationCode":"long range = (long) high - low;\nif (range > Integer.MAX_VALUE) {\n    throw new IllegalStateException(\"reserved session range must be <= \" + Integer.MAX_VALUE);\n}\nio.aeron.driver.Configuration.validateSessionIdRange(low, high);","typeGuard":null,"tryCatchPattern":"try {\n    Configuration.validateSessionIdRange(low, high);\n} catch (ConfigurationException e) {\n    if (e.getMessage().contains(\"too large\")) {\n        // narrow the range\n        Configuration.validateSessionIdRange(low, (int)Math.min((long)low + Integer.MAX_VALUE, high & 0xFFFFFFFFL));\n    } else { throw e; }\n}","preventionTips":["Compute the range as a long before validating","Keep reserved ranges well below 2^31 ids","Prefer explicit session ids for the full-space cases instead of a huge reserved range"],"tags":["aeron","configuration","session-id","range"],"backgroundTag":"value-out-of-range","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}