{"record":{"id":"cb2745e2fa97b70f","repo":"aeron-io/aeron","slug":"page-size-more-than-max-size-of-page-max-size-page-size","errorCode":null,"errorMessage":"Page size more than max size of {PAGE_MAX_SIZE}: page size={pageSize}","messagePattern":"Page size more than max size of (.+?): page size=(.+?)","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java","lineNumber":488,"sourceCode":"    }\n\n    /**\n     * Check that page size is valid and alignment is valid.\n     *\n     * @param pageSize to be checked.\n     * @throws IllegalStateException if the size is not as expected.\n     */\n    public static void checkPageSize(final int pageSize)\n    {\n        if (pageSize < PAGE_MIN_SIZE)\n        {\n            throw new IllegalStateException(\n                \"Page size less than min size of \" + PAGE_MIN_SIZE + \": page size=\" + pageSize);\n        }\n\n        if (pageSize > PAGE_MAX_SIZE)\n        {\n            throw new IllegalStateException(\n                \"Page size more than max size of \" + PAGE_MAX_SIZE + \": page size=\" + pageSize);\n        }\n\n        if (!BitUtil.isPowerOfTwo(pageSize))\n        {\n            throw new IllegalStateException(\"Page size not a power of 2: page size=\" + pageSize);\n        }\n    }\n\n    /**\n     * Get the value of the initial Term id used for this log.\n     *\n     * @param metadataBuffer containing the meta data.\n     * @return the value of the initial Term id used for this log.\n     */\n    public static int initialTermId(final UnsafeBuffer metadataBuffer)\n    {\n        return metadataBuffer.getInt(LOG_INITIAL_TERM_ID_OFFSET);","sourceCodeStart":470,"sourceCodeEnd":506,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java#L470-L506","documentation":"LogBufferDescriptor.checkPageSize enforces that the page size does not exceed PAGE_MAX_SIZE (1GB). A pageSize above that cap is rejected with IllegalStateException because log buffer files and offset arithmetic assume bounded page sizes.","triggerScenarios":"Configuring filePageSize in the media driver context or channel term parameters with a value greater than 1073741824 bytes; passing such a value directly to checkPageSize.","commonSituations":"Attempting to optimize large-file I/O by inflating page size to 2GB/4GB, or unit mistakes in generated configuration (bytes vs GB).","solutions":["Reduce filePageSize to at most 1073741824 (PAGE_MAX_SIZE)","Prefer typical values like 4096–1MB unless profiling shows a need for larger pages","Guard configuration parsing with pageSize <= LogBufferDescriptor.PAGE_MAX_SIZE before applying it"],"exampleFix":"// before\ndriverCtx.filePageSize(2L * 1024 * 1024 * 1024);\n// after\ndriverCtx.filePageSize(1024 * 1024); // 1MB, within PAGE_MAX_SIZE","handlingStrategy":"validation","validationCode":"if (pageSize > LogBufferDescriptor.PAGE_MAX_SIZE) { pageSize = LogBufferDescriptor.PAGE_MAX_SIZE; }","typeGuard":null,"tryCatchPattern":"try { driver = MediaDriver.launch(ctx); } catch (final IllegalStateException ex) { if (ex.getMessage().contains(\"Page size more than max\")) { ctx.filePageSize(LogBufferDescriptor.PAGE_MAX_SIZE); driver = MediaDriver.launch(ctx); } else throw ex; }","preventionTips":["Cap page size at 1GB in config validation","Beware 2GB/4GB page-size 'tuning' advice; verify against PAGE_MAX_SIZE","Parse numeric config with explicit long/int range checks"],"tags":["aeron","configuration","page-size","validation"],"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"}